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

package/src/packlets/context/convert/index.ts

@@ -0,0 +1,23 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+export * from './decls';

package/src/packlets/context/index.ts

@@ -0,0 +1,27 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import * as Convert from './convert';
+export * from './contextDecls';
+export * from './contextToken';
+
+export { Convert };

package/src/packlets/decisions/abstractDecision.ts

@@ -0,0 +1,87 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { captureResult, Result } from '@fgv/ts-utils';
+import { ConditionSet } from '../conditions';
+import { Candidate } from './candidate';
+import { Decision } from './decision';
+import * as ResourceJson from '../resource-json';
+
+/**
+ * Parameters to create an {@link Decisions.AbstractDecision | AbstractDecision}.
+ * @public
+ */
+export interface IAbstractDecisionCreateParams {
+  conditionSets: ConditionSet[];
+  index?: number;
+}
+
+/**
+ * An abstract decision represents a class of decisions with candidates
+ * that differ only in value.  It is a {@link Decisions.Decision | IDecision<number>}
+ * in which the `number` values are sequentially assigned indexes.
+ * This allows us to represent each related {@link Decisions.IDecision | decision} as an
+ * {@link Decisions.AbstractDecision | abstract decision} and a matching array containing
+ * the corresponding value for each candidate.  This representation is highly cacheable.
+ * @public
+ */
+export class AbstractDecision extends Decision<number> {
+  /**
+   * Constructor for an {@link Decisions.AbstractDecision | AbstractDecision} object.
+   * @param params - {@link Decisions.IAbstractDecisionCreateParams | Parameters}
+   * used to create the decision.
+   * @public
+   */
+  protected constructor(params: IAbstractDecisionCreateParams) {
+    const candidates = Array.from(params.conditionSets)
+      .map((conditionSet, value) => Candidate.createCandidate({ conditionSet, value }).orThrow())
+      .sort(Candidate.compare);
+    super({ candidates, index: params.index, isAbstract: true });
+  }
+
+  /**
+   * Creates a new {@link Decisions.AbstractDecision | AbstractDecision} object.
+   * @param params - {@link Decisions.IAbstractDecisionCreateParams | Parameters}
+   * used to create the decision.
+   * @returns `Success` with the new decision if successful, or `Failure` with an
+   * error message if not.
+   * @public
+   */
+  public static createAbstractDecision(params: IAbstractDecisionCreateParams): Result<AbstractDecision> {
+    return captureResult(() => new AbstractDecision(params));
+  }
+
+  /**
+   * Converts this abstract decision to a compiled abstract decision representation.
+   * @param options - Optional compilation options controlling the output format.
+   * @returns A compiled abstract decision object that can be used for serialization or runtime processing.
+   * @public
+   */
+  public toCompiled(
+    options?: ResourceJson.Compiled.ICompiledResourceOptions
+  ): ResourceJson.Compiled.ICompiledAbstractDecision {
+    return {
+      conditionSets: this.candidates.map((c) => c.conditionSet.index!),
+      ...(options?.includeMetadata === true ? { metadata: { key: this.key } } : {})
+    };
+  }
+}

package/src/packlets/decisions/abstractDecisionCollector.ts

@@ -0,0 +1,122 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { captureResult, Collections, Result, fail, succeed, ValidatingCollector } from '@fgv/ts-utils';
+import { AbstractDecision } from './abstractDecision';
+import { Convert as CommonConvert, DecisionIndex, DecisionKey, Validate } from '../common';
+import { ConditionSet, ReadOnlyConditionSetCollector } from '../conditions';
+
+/**
+ * Parameters for creating a {@link Decisions.AbstractDecisionCollector | AbstractDecisionCollector}.
+ * @public
+ */
+export interface IAbstractDecisionCollectorCreateParams {
+  /**
+   * {@link Conditions.ReadOnlyConditionSetCollector | ConditionSetCollector} used to create conditions
+   * sets for decisions in this collector.
+   */
+  conditionSets: ReadOnlyConditionSetCollector;
+}
+
+/**
+ * A `ValidatingCollector` for {@link Decisions.AbstractDecision | AbstractDecisions}.
+ * @public
+ */
+export class AbstractDecisionCollector extends ValidatingCollector<AbstractDecision> {
+  /**
+   * The {@link Conditions.ReadOnlyConditionSetCollector | ConditionSetCollector} used to create conditions
+   * sets for decisions in this collector.
+   */
+  public readonly conditionSets: ReadOnlyConditionSetCollector;
+
+  /**
+   * The empty decision (no condition sets) for this collector.
+   */
+  public get emptyDecision(): AbstractDecision {
+    return this.getAt(AbstractDecisionCollector.EmptyDecisionIndex).orThrow();
+  }
+
+  /**
+   * The default-only decision (one condition set with no conditions) for this collector.
+   */
+  public get defaultOnlyDecision(): AbstractDecision {
+    return this.getAt(AbstractDecisionCollector.DefaultOnlyDecisionIndex).orThrow();
+  }
+
+  /**
+   * The index for the empty decision.
+   */
+  public static readonly EmptyDecisionIndex: DecisionIndex = Validate.toDecisionIndex(0).orThrow();
+
+  /**
+   * The index for the default-only decision.
+   */
+  public static readonly DefaultOnlyDecisionIndex: DecisionIndex = Validate.toDecisionIndex(1).orThrow();
+
+  /**
+   * Creates a new instance of {@link Decisions.AbstractDecisionCollector | AbstractDecisionCollector}.
+   */
+  protected constructor(params: IAbstractDecisionCollectorCreateParams) {
+    super({
+      converters: new Collections.KeyValueConverters<DecisionKey, AbstractDecision>({
+        key: CommonConvert.decisionKey,
+        value: (from: unknown) => this._toAbstractDecision(from)
+      })
+    });
+    this.conditionSets = params.conditionSets;
+    this.add(AbstractDecision.createAbstractDecision({ conditionSets: [] }).orThrow()).orThrow();
+    const cs = this.conditionSets.validating.get('').orThrow();
+    this.add(AbstractDecision.createAbstractDecision({ conditionSets: [cs] }).orThrow()).orThrow();
+  }
+
+  /**
+   * Creates a new instance of {@link Decisions.AbstractDecisionCollector | AbstractDecisionCollector}.
+   * @returns `Success` with the new instance, or `Failure` with an error if the instance could not be created.
+   */
+  public static create(params: IAbstractDecisionCollectorCreateParams): Result<AbstractDecisionCollector> {
+    return captureResult(() => new AbstractDecisionCollector(params));
+  }
+
+  private _toAbstractDecision(from: unknown): Result<AbstractDecision> {
+    /* c8 ignore next 3 - functional code path tested but coverage intermittently missed */
+    if (from instanceof AbstractDecision) {
+      return succeed(from);
+    }
+    if (this._isConditionSetArray(from)) {
+      return AbstractDecision.createAbstractDecision({
+        conditionSets: from
+      });
+    }
+    /* c8 ignore next 2 - functional code path tested but coverage intermittently missed */
+    return fail('invalid value: not an abstract decision or condition sets');
+  }
+
+  private _isConditionSetArray(from: unknown): from is ConditionSet[] {
+    return Array.isArray(from) && from.every((e) => e instanceof ConditionSet);
+  }
+}
+
+/**
+ * A read-only {@link Decisions.AbstractDecisionCollector | AbstractDecisionCollector}.
+ * @public
+ */
+export type ReadOnlyAbstractDecisionCollector = Collections.IReadOnlyValidatingCollector<AbstractDecision>;

package/src/packlets/decisions/candidate.ts

@@ -0,0 +1,101 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { JsonValue } from '@fgv/ts-json-base';
+import { ConditionSet } from '../conditions';
+import { captureResult, Result } from '@fgv/ts-utils';
+import { ResourceValueMergeMethod } from '../common';
+
+/**
+ * A {@link Decisions.ICandidate | resource candidate} represents a single
+ * possible value for some resource, with the conditions under which it is valid.
+ * @public
+ */
+export interface ICandidate<TVALUE extends JsonValue = JsonValue> {
+  readonly conditionSet: ConditionSet;
+  readonly value: TVALUE;
+  readonly isPartial?: boolean;
+  readonly mergeMethod?: ResourceValueMergeMethod;
+}
+
+/**
+ * Simple implementation of {@link Decisions.ICandidate | ICandidate} with
+ * helper methods for sorting and presentation.
+ * @public
+ */
+export class Candidate<TVALUE extends JsonValue = JsonValue> implements ICandidate<TVALUE> {
+  public readonly conditionSet: ConditionSet;
+  public readonly value: TVALUE;
+  public readonly isPartial: boolean;
+  public readonly mergeMethod: ResourceValueMergeMethod;
+
+  /**
+   * Key of the condition set for this candidate.
+   */
+  public get key(): string {
+    return this.conditionSet.key;
+  }
+
+  /**
+   * Construct a new {@link Decisions.Candidate | Candidate}.
+   * @param params - The {@link Decisions.ICandidate | parameters} to use to create the
+   * new candidate.
+   */
+  protected constructor(params: ICandidate<TVALUE>) {
+    this.conditionSet = params.conditionSet;
+    this.value = params.value;
+    this.isPartial = params.isPartial === true;
+    this.mergeMethod = params.mergeMethod ?? 'augment';
+  }
+
+  /**
+   * Create a new {@link Decisions.Candidate | candidate}.
+   * @param params - The {@link Decisions.ICandidate | parameters} to use to create the
+   * new candidate.
+   * @returns `Success` with the new candidate if successful, or `Failure` if the
+   * candidate could not be created.
+   */
+  public static createCandidate<TVALUE extends JsonValue>(
+    params: ICandidate<TVALUE>
+  ): Result<Candidate<TVALUE>> {
+    return captureResult(() => new Candidate(params));
+  }
+
+  /**
+   * Compare two {@link Decisions.ICandidate | candidates} for sorting purposes.
+   * @param c1 - The first candidate to compare.
+   * @param c2 - The second candidate to compare.
+   * @returns A negative number if c1 should come before c2, a positive number if c1 should
+   * come after c2, or zero if they are equivalent.
+   */
+  public static compare(c1: ICandidate, c2: ICandidate): number {
+    return ConditionSet.compare(c1.conditionSet, c2.conditionSet);
+  }
+
+  /**
+   * Returns a string representation of the {@link Decisions.Candidate | candidate}.
+   * @returns A string representation of this candidate.
+   */
+  public toString(): string {
+    return `${this.key}: ${JSON.stringify(this.value)}`;
+  }
+}

package/src/packlets/decisions/common.ts

@@ -0,0 +1,37 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { DecisionIndex, DecisionKey } from '../common';
+import { JsonValue } from '@fgv/ts-json-base';
+import { ICandidate } from './candidate';
+
+/**
+ * Represents a decision, which is comprised of zero or more
+ * {@link Decisions.Candidate | candidates}, each of which represents a possible
+ * value for some resource, along with the conditions under which that value is valid.
+ * @public
+ */
+export interface IDecision<TVALUE extends JsonValue = JsonValue> {
+  key: DecisionKey;
+  candidates: ReadonlyArray<ICandidate<TVALUE>>;
+  index?: DecisionIndex;
+}

package/src/packlets/decisions/concreteDecision.ts

@@ -0,0 +1,157 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { JsonValue } from '@fgv/ts-json-base';
+import { Candidate, ICandidate } from './candidate';
+import { IDecision } from './common';
+import { AbstractDecisionCollector } from './abstractDecisionCollector';
+import { AbstractDecision } from './abstractDecision';
+import { captureResult, Collections, mapResults, Result, fail, succeed } from '@fgv/ts-utils';
+import { ConditionSet } from '../conditions';
+import { Convert as CommonConvert, DecisionIndex, DecisionKey } from '../common';
+import { Decision } from './decision';
+
+/**
+ * Parameters used to create a new {@link Decisions.ConcreteDecision | ConcreteDecision},
+ * given an {@link Decisions.AbstractDecisionCollector | AbstractDecisionCollector} and a
+ * list of {@link Decisions.ICandidate | candidates}.
+ * @public
+ */
+export interface IConcreteDecisionCreateParams<TVALUE extends JsonValue = JsonValue> {
+  decisions: AbstractDecisionCollector;
+  candidates: ReadonlyArray<ICandidate<TVALUE>>;
+  index?: number;
+}
+
+/**
+ * Protected constructor parameters for {@link Decisions.ConcreteDecision | ConcreteDecision},
+ * used to create a new concrete decision from an existing {@link Decisions.AbstractDecision | AbstractDecision}
+ * and a list of values.
+ * @public
+ */
+export interface IConcreteDecisionConstructorParams<TVALUE extends JsonValue = JsonValue> {
+  baseDecision: AbstractDecision;
+  values: TVALUE[];
+  index?: DecisionIndex;
+}
+
+/**
+ * A {@link Decisions.ConcreteDecision | concrete decision} is a {@link Decisions.IDecision | decision}
+ * implemented as a reference to a common {@link Decisions.AbstractDecision | abstract decision} and a list of
+ * values that correspond to the candidates in the abstract decision.  This allows us to represent a large
+ * number of related decisions with a single abstract decision and a list of values.
+ * @public
+ */
+export class ConcreteDecision<TVALUE extends JsonValue = JsonValue> implements IDecision<TVALUE> {
+  public readonly baseDecision: AbstractDecision;
+  public readonly values: TVALUE[];
+  public readonly candidates: ReadonlyArray<ICandidate<TVALUE>>;
+
+  /**
+   * Unique global key for this decision, derived from the condition set and
+   * candidate values.
+   */
+  public get key(): DecisionKey {
+    return this._collectible.key;
+  }
+
+  /**
+   * Unique global index for this decision.
+   */
+  public get index(): DecisionIndex | undefined {
+    return this._collectible.index;
+  }
+
+  private _collectible: Collections.Collectible<DecisionKey, DecisionIndex>;
+
+  /**
+   * Constructor for a {@link Decisions.ConcreteDecision | ConcreteDecision} object.
+   * @param params - {@link Decisions.IConcreteDecisionConstructorParams | Parameters}
+   * used to create the decision.
+   * @public
+   */
+  protected constructor(params: IConcreteDecisionConstructorParams<TVALUE>) {
+    this.baseDecision = params.baseDecision;
+    this.values = params.values;
+    this.candidates = this.baseDecision.candidates.map((candidate) => {
+      const value = this.values[candidate.value];
+      return Candidate.createCandidate({ conditionSet: candidate.conditionSet, value }).orThrow();
+    });
+    this._collectible = new Collections.Collectible({
+      key: Decision.getKey(this.candidates),
+      index: params.index,
+      indexConverter: CommonConvert.decisionIndex
+    });
+  }
+
+  /**
+   * Creates a new {@link Decisions.ConcreteDecision | ConcreteDecision} object.
+   * @param params - {@link Decisions.IConcreteDecisionCreateParams | Parameters}
+   * used to create the decision.
+   * @returns `Success` with the new decision if successful, or `Failure` with an
+   * error message if not.
+   * @public
+   */
+  public static create<TVALUE extends JsonValue = JsonValue>(
+    params: IConcreteDecisionCreateParams<TVALUE>
+  ): Result<ConcreteDecision<TVALUE>> {
+    const conditionSets = params.candidates
+      .map((candidate) => candidate.conditionSet)
+      .sort(ConditionSet.compare)
+      .reverse();
+
+    const getBase = params.decisions.validating.getOrAdd(conditionSets);
+    /* c8 ignore next 3 - defense in depth against internal error hard to repro */
+    if (getBase.isFailure()) {
+      return fail<ConcreteDecision<TVALUE>>(getBase.message);
+    }
+    const baseDecision = getBase.value;
+    return mapResults(
+      params.candidates.map((candidate, index) => {
+        /* c8 ignore next 5 - defense in depth against internal error hard to repro */
+        if (candidate.conditionSet.key !== baseDecision.candidates[index].conditionSet.key) {
+          return fail<TVALUE>(
+            `${candidate.conditionSet.key}: Candidate does not match base decision ${candidate.conditionSet.key}`
+          );
+        }
+        return succeed(candidate.value);
+      })
+    ).onSuccess((values) => {
+      /* c8 ignore next 5 - defense in depth against invalid index conversion */
+      if (params.index) {
+        return CommonConvert.decisionIndex.convert(params.index).onSuccess((index) => {
+          return captureResult(() => new ConcreteDecision({ baseDecision, values, index }));
+        });
+      }
+      return captureResult(() => new ConcreteDecision({ baseDecision, values }));
+    });
+  }
+
+  /**
+   * Sets the index for this decision.  Once set, index is immutable.
+   * @param index - The index to set.
+   * @returns `Success` with the new index if successful, or `Failure` with an error message if not.
+   */
+  public setIndex(index: number): Result<DecisionIndex> {
+    return this._collectible.setIndex(index);
+  }
+}