@higher.archi/boe 1.0.26 → 1.0.28

package/src/engines/negotiation/strategy.ts

@@ -0,0 +1,587 @@
+/**
+ * Negotiation Engine Strategy
+ *
+ * Core execution logic for all negotiation strategies:
+ * - zopa-analysis: Compute zones of possible agreement per dimension
+ * - concession-planning: Simulate round-by-round concession trajectories
+ * - package-optimization: Find optimal deal packages within the ZOPA
+ */
+
+import type {
+  CompiledNegotiationRuleSet,
+  CompiledZopaAnalysisRuleSet,
+  CompiledConcessionPlanningRuleSet,
+  CompiledPackageOptimizationRuleSet,
+  CompiledValueFunction,
+  CompiledPartyProfile,
+  NegotiationDimension,
+  NegotiationOptions,
+  NegotiationResult,
+  ZopaRange,
+  ConcessionStep,
+  PackageCandidate,
+  DealOutcome,
+  PartyPosition
+} from './types';
+
+// ========================================
+// Executor
+// ========================================
+
+export class NegotiationExecutor {
+  run(
+    ruleSet: CompiledNegotiationRuleSet,
+    options: NegotiationOptions = {}
+  ): NegotiationResult {
+    switch (ruleSet.strategy) {
+      case 'zopa-analysis':
+        return this.runZopaAnalysis(ruleSet);
+      case 'concession-planning':
+        return this.runConcessionPlanning(ruleSet, options);
+      case 'package-optimization':
+        return this.runPackageOptimization(ruleSet, options);
+      default:
+        throw new Error(`Unknown negotiation strategy: '${(ruleSet as any).strategy}'`);
+    }
+  }
+
+  // ========================================
+  // ZOPA Analysis
+  // ========================================
+
+  private runZopaAnalysis(
+    ruleSet: CompiledZopaAnalysisRuleSet
+  ): NegotiationResult {
+    const startTime = performance.now();
+
+    const [partyA, partyB] = ruleSet.parties;
+    const ranges: ZopaRange[] = [];
+    let hasAgreement = true;
+
+    for (const dim of ruleSet.dimensions) {
+      const posA = findPosition(partyA, dim.id);
+      const posB = findPosition(partyB, dim.id);
+
+      if (!posA || !posB) {
+        hasAgreement = false;
+        continue;
+      }
+
+      const range = computeZopaRange(dim, posA, posB);
+
+      if (range === null) {
+        hasAgreement = false;
+      } else {
+        ranges.push(range);
+      }
+    }
+
+    // zopaVolume = product of normalized range sizes
+    let zopaVolume = 0;
+    if (hasAgreement && ranges.length > 0) {
+      zopaVolume = 1;
+      for (const range of ranges) {
+        const dim = ruleSet.dimensions.find(d => d.id === range.dimensionId)!;
+        const posA = findPosition(partyA, dim.id)!;
+        const posB = findPosition(partyB, dim.id)!;
+        const fullSpan = Math.abs(
+          Math.max(posA.ideal, posA.walkaway, posB.ideal, posB.walkaway) -
+          Math.min(posA.ideal, posA.walkaway, posB.ideal, posB.walkaway)
+        );
+        const normalizedSize = fullSpan > 0 ? range.size / fullSpan : 0;
+        zopaVolume *= normalizedSize;
+      }
+    }
+
+    const outcome: DealOutcome = hasAgreement ? 'agreed' : 'no-zopa';
+
+    // BATNA comparison -- use midpoint of ZOPA as deal value
+    const batnaComparison = buildBatnaComparison(
+      ruleSet.parties,
+      ruleSet.valueWeights,
+      ruleSet.dimensions,
+      hasAgreement ? ranges : [],
+      hasAgreement
+    );
+
+    const executionTimeMs = round(performance.now() - startTime, 2);
+
+    return {
+      outcome,
+      zopa: {
+        ranges,
+        hasAgreement,
+        zopaVolume: round(zopaVolume, 6)
+      },
+      batnaComparison,
+      strategy: 'zopa-analysis',
+      executionTimeMs
+    };
+  }
+
+  // ========================================
+  // Concession Planning
+  // ========================================
+
+  private runConcessionPlanning(
+    ruleSet: CompiledConcessionPlanningRuleSet,
+    options: NegotiationOptions
+  ): NegotiationResult {
+    const startTime = performance.now();
+
+    const { style, rounds, startingPosition } = ruleSet.config;
+    const [partyA, partyB] = ruleSet.parties;
+    const steps: ConcessionStep[] = [];
+    let convergenceRound: number | undefined;
+    let finalDeal: Record<string, number> | undefined;
+
+    // Initialize current offers per party per dimension
+    const currentOffers: Record<string, Record<string, number>> = {};
+    for (const party of ruleSet.parties) {
+      currentOffers[party.id] = {};
+      for (const pos of party.positions) {
+        if (startingPosition === 'midpoint') {
+          currentOffers[party.id][pos.dimensionId] = (pos.ideal + pos.acceptable) / 2;
+        } else {
+          currentOffers[party.id][pos.dimensionId] = pos.ideal;
+        }
+      }
+    }
+
+    for (let r = 1; r <= rounds; r++) {
+      for (const party of ruleSet.parties) {
+        const otherParty = party === partyA ? partyB : partyA;
+        const weights = ruleSet.valueWeights[party.id] || [];
+
+        for (const pos of party.positions) {
+          const dimId = pos.dimensionId;
+          const current = currentOffers[party.id][dimId];
+          const otherCurrent = currentOffers[otherParty.id][dimId];
+          const gap = otherCurrent - current;
+
+          // Compute inverse weight for this dimension -- concede more on low-priority
+          const dimWeight = weights.find(w => w.dimensionId === dimId);
+          const inverseWeight = dimWeight ? (1 - dimWeight.weight) : 0.5;
+
+          let concession = 0;
+
+          switch (style) {
+            case 'aggressive':
+              concession = gap * 0.5 * Math.pow(0.7, r - 1) * inverseWeight;
+              break;
+            case 'moderate': {
+              const totalTravel = pos.ideal - pos.acceptable;
+              const equalStep = rounds > 0 ? totalTravel / rounds : 0;
+              // Direction-aware concession
+              concession = Math.sign(gap) * Math.abs(equalStep) * inverseWeight;
+              break;
+            }
+            case 'collaborative': {
+              const fraction = Math.pow(r / rounds, 2);
+              concession = gap * fraction * inverseWeight;
+              break;
+            }
+          }
+
+          currentOffers[party.id][dimId] = current + concession;
+        }
+
+        // Compute total value for this party's current offer
+        const totalValue = computePartyValue(
+          party, currentOffers[party.id], ruleSet.dimensions, weights
+        );
+
+        const step: ConcessionStep = {
+          round: r,
+          partyId: party.id,
+          offers: { ...currentOffers[party.id] },
+          totalValue: round(totalValue, 4)
+        };
+
+        steps.push(step);
+
+        if (options.onStep) {
+          options.onStep(step);
+        }
+      }
+
+      // Check convergence -- all dimensions within 1% tolerance
+      const converged = ruleSet.dimensions.every(dim => {
+        const offerA = currentOffers[partyA.id][dim.id];
+        const offerB = currentOffers[partyB.id][dim.id];
+        const posA = findPosition(partyA, dim.id);
+        const posB = findPosition(partyB, dim.id);
+        if (!posA || !posB) return false;
+
+        const fullRange = Math.abs(
+          Math.max(posA.ideal, posA.walkaway, posB.ideal, posB.walkaway) -
+          Math.min(posA.ideal, posA.walkaway, posB.ideal, posB.walkaway)
+        );
+        const tolerance = fullRange * 0.01;
+        return Math.abs(offerA - offerB) <= tolerance;
+      });
+
+      if (converged && convergenceRound === undefined) {
+        convergenceRound = r;
+        finalDeal = {};
+        for (const dim of ruleSet.dimensions) {
+          finalDeal[dim.id] = round(
+            (currentOffers[partyA.id][dim.id] + currentOffers[partyB.id][dim.id]) / 2,
+            4
+          );
+        }
+        break;
+      }
+    }
+
+    const hasAgreement = convergenceRound !== undefined;
+    const outcome: DealOutcome = hasAgreement ? 'agreed' : 'no-zopa';
+
+    // Compute ZOPA for BATNA comparison
+    const zopaRanges: ZopaRange[] = [];
+    for (const dim of ruleSet.dimensions) {
+      const posA = findPosition(partyA, dim.id);
+      const posB = findPosition(partyB, dim.id);
+      if (posA && posB) {
+        const range = computeZopaRange(dim, posA, posB);
+        if (range) zopaRanges.push(range);
+      }
+    }
+
+    const batnaComparison = buildBatnaComparison(
+      ruleSet.parties,
+      ruleSet.valueWeights,
+      ruleSet.dimensions,
+      hasAgreement && finalDeal
+        ? ruleSet.dimensions.map(d => ({
+            dimensionId: d.id,
+            lower: finalDeal![d.id],
+            upper: finalDeal![d.id],
+            size: 0
+          }))
+        : zopaRanges,
+      hasAgreement
+    );
+
+    const executionTimeMs = round(performance.now() - startTime, 2);
+
+    return {
+      outcome,
+      concessionPlan: {
+        steps,
+        convergenceRound,
+        finalDeal
+      },
+      batnaComparison,
+      strategy: 'concession-planning',
+      executionTimeMs
+    };
+  }
+
+  // ========================================
+  // Package Optimization
+  // ========================================
+
+  private runPackageOptimization(
+    ruleSet: CompiledPackageOptimizationRuleSet,
+    options: NegotiationOptions
+  ): NegotiationResult {
+    const startTime = performance.now();
+
+    const [partyA, partyB] = ruleSet.parties;
+    const { sampleSize, objectiveWeights } = ruleSet.config;
+
+    // 1. Compute ZOPA ranges
+    const zopaRanges: ZopaRange[] = [];
+    let hasAgreement = true;
+
+    for (const dim of ruleSet.dimensions) {
+      const posA = findPosition(partyA, dim.id);
+      const posB = findPosition(partyB, dim.id);
+
+      if (!posA || !posB) {
+        hasAgreement = false;
+        continue;
+      }
+
+      const range = computeZopaRange(dim, posA, posB);
+      if (range === null) {
+        hasAgreement = false;
+      } else {
+        zopaRanges.push(range);
+      }
+    }
+
+    // 2. If no ZOPA, return no-zopa outcome
+    if (!hasAgreement || zopaRanges.length === 0) {
+      const batnaComparison = buildBatnaComparison(
+        ruleSet.parties, ruleSet.valueWeights, ruleSet.dimensions, [], false
+      );
+
+      const executionTimeMs = round(performance.now() - startTime, 2);
+
+      return {
+        outcome: 'no-zopa',
+        zopa: {
+          ranges: zopaRanges,
+          hasAgreement: false,
+          zopaVolume: 0
+        },
+        batnaComparison,
+        strategy: 'package-optimization',
+        executionTimeMs
+      };
+    }
+
+    // 3. Sample random points within ZOPA ranges
+    const weightsA = ruleSet.valueWeights[partyA.id] || [];
+    const weightsB = ruleSet.valueWeights[partyB.id] || [];
+    const candidates: PackageCandidate[] = [];
+
+    for (let i = 0; i < sampleSize; i++) {
+      const dims: Record<string, number> = {};
+
+      for (const range of zopaRanges) {
+        dims[range.dimensionId] = range.lower + Math.random() * range.size;
+      }
+
+      // Compute party values (0-1 normalized within their range, weighted)
+      const partyAValue = computePartyValue(
+        partyA, dims, ruleSet.dimensions, weightsA
+      );
+      const partyBValue = computePartyValue(
+        partyB, dims, ruleSet.dimensions, weightsB
+      );
+
+      const closeProbability = round(Math.sqrt(partyAValue * partyBValue), 4);
+      const marginScore = round(partyAValue, 4);
+      const compositeScore = round(
+        objectiveWeights.closeProb * closeProbability +
+        objectiveWeights.margin * marginScore,
+        4
+      );
+
+      const candidate: PackageCandidate = {
+        dimensions: roundDimensions(dims),
+        partyAValue: round(partyAValue, 4),
+        partyBValue: round(partyBValue, 4),
+        closeProbability,
+        marginScore,
+        compositeScore
+      };
+
+      candidates.push(candidate);
+
+      if (options.onPackage) {
+        options.onPackage(candidate);
+      }
+    }
+
+    // 4. Sort by compositeScore descending, take top 10
+    candidates.sort((a, b) => b.compositeScore - a.compositeScore);
+    const topPackages = candidates.slice(0, 10);
+    const recommended = topPackages[0];
+
+    // 5. Compare best against BATNA
+    const batnaComparison = buildBatnaComparison(
+      ruleSet.parties,
+      ruleSet.valueWeights,
+      ruleSet.dimensions,
+      // Use recommended package dimensions as the deal point
+      ruleSet.dimensions.map(d => ({
+        dimensionId: d.id,
+        lower: recommended.dimensions[d.id] ?? 0,
+        upper: recommended.dimensions[d.id] ?? 0,
+        size: 0
+      })),
+      true
+    );
+
+    // Check if BATNA is preferred for either party
+    let outcome: DealOutcome = 'agreed';
+    for (const partyId of Object.keys(batnaComparison)) {
+      if (batnaComparison[partyId].surplus < 0) {
+        outcome = 'batna-preferred';
+        break;
+      }
+    }
+
+    // Compute zopaVolume
+    let zopaVolume = 1;
+    for (const range of zopaRanges) {
+      const dim = ruleSet.dimensions.find(d => d.id === range.dimensionId)!;
+      const posA = findPosition(partyA, dim.id)!;
+      const posB = findPosition(partyB, dim.id)!;
+      const fullSpan = Math.abs(
+        Math.max(posA.ideal, posA.walkaway, posB.ideal, posB.walkaway) -
+        Math.min(posA.ideal, posA.walkaway, posB.ideal, posB.walkaway)
+      );
+      const normalizedSize = fullSpan > 0 ? range.size / fullSpan : 0;
+      zopaVolume *= normalizedSize;
+    }
+
+    const executionTimeMs = round(performance.now() - startTime, 2);
+
+    return {
+      outcome,
+      zopa: {
+        ranges: zopaRanges,
+        hasAgreement: true,
+        zopaVolume: round(zopaVolume, 6)
+      },
+      recommendedPackage: recommended,
+      allPackages: topPackages,
+      batnaComparison,
+      strategy: 'package-optimization',
+      executionTimeMs
+    };
+  }
+}
+
+// ========================================
+// Module-Level Helpers
+// ========================================
+
+function findPosition(party: CompiledPartyProfile, dimensionId: string): PartyPosition | undefined {
+  return party.positions.find(p => p.dimensionId === dimensionId);
+}
+
+/**
+ * Compute the ZOPA range for a single dimension.
+ *
+ * For 'higher-is-better': the party who wants higher values has range
+ * [walkaway, ideal], and the party who wants lower values has range
+ * [ideal, walkaway]. The ZOPA is the intersection.
+ *
+ * For 'lower-is-better': reversed logic applies.
+ *
+ * Returns null if there is no overlap.
+ */
+function computeZopaRange(
+  dim: NegotiationDimension,
+  posA: PartyPosition,
+  posB: PartyPosition
+): ZopaRange | null {
+  let rangeALow: number, rangeAHigh: number;
+  let rangeBLow: number, rangeBHigh: number;
+
+  if (dim.direction === 'higher-is-better') {
+    // Party A: [walkaway, ideal], Party B: [walkaway, ideal]
+    rangeALow = Math.min(posA.walkaway, posA.ideal);
+    rangeAHigh = Math.max(posA.walkaway, posA.ideal);
+    rangeBLow = Math.min(posB.walkaway, posB.ideal);
+    rangeBHigh = Math.max(posB.walkaway, posB.ideal);
+  } else {
+    // lower-is-better
+    rangeALow = Math.min(posA.ideal, posA.walkaway);
+    rangeAHigh = Math.max(posA.ideal, posA.walkaway);
+    rangeBLow = Math.min(posB.ideal, posB.walkaway);
+    rangeBHigh = Math.max(posB.ideal, posB.walkaway);
+  }
+
+  // Intersection
+  const lower = Math.max(rangeALow, rangeBLow);
+  const upper = Math.min(rangeAHigh, rangeBHigh);
+  const size = upper - lower;
+
+  if (size < 0) {
+    return null;
+  }
+
+  return {
+    dimensionId: dim.id,
+    lower: round(lower, 4),
+    upper: round(upper, 4),
+    size: round(size, 4)
+  };
+}
+
+/**
+ * Compute a party's normalized value (0-1) for a given set of dimension values.
+ * Value is computed as the weighted sum of per-dimension normalized scores.
+ */
+function computePartyValue(
+  party: CompiledPartyProfile,
+  dimensionValues: Record<string, number>,
+  dimensions: NegotiationDimension[],
+  weights: CompiledValueFunction[]
+): number {
+  let totalValue = 0;
+
+  for (const dim of dimensions) {
+    const pos = findPosition(party, dim.id);
+    if (!pos) continue;
+
+    const value = dimensionValues[dim.id];
+    if (value === undefined) continue;
+
+    const dimWeight = weights.find(w => w.dimensionId === dim.id);
+    const weight = dimWeight ? dimWeight.weight : 0;
+
+    // Normalize within party's range [walkaway, ideal] to [0, 1]
+    const range = pos.ideal - pos.walkaway;
+    let normalized: number;
+    if (range === 0) {
+      normalized = value === pos.ideal ? 1 : 0;
+    } else {
+      normalized = (value - pos.walkaway) / range;
+      normalized = Math.max(0, Math.min(1, normalized));
+    }
+
+    totalValue += normalized * weight;
+  }
+
+  return totalValue;
+}
+
+/**
+ * Build BATNA comparison for both parties.
+ * Uses the midpoint of ZOPA ranges (or deal point) as the deal value.
+ */
+function buildBatnaComparison(
+  parties: [CompiledPartyProfile, CompiledPartyProfile],
+  valueWeights: Record<string, CompiledValueFunction[]>,
+  dimensions: NegotiationDimension[],
+  ranges: ZopaRange[],
+  hasAgreement: boolean
+): Record<string, { dealValue: number; batnaValue: number; surplus: number }> {
+  const result: Record<string, { dealValue: number; batnaValue: number; surplus: number }> = {};
+
+  // Build deal point from ranges (midpoint)
+  const dealPoint: Record<string, number> = {};
+  for (const range of ranges) {
+    dealPoint[range.dimensionId] = (range.lower + range.upper) / 2;
+  }
+
+  for (const party of parties) {
+    const weights = valueWeights[party.id] || [];
+    const dealValue = hasAgreement
+      ? round(computePartyValue(party, dealPoint, dimensions, weights), 4)
+      : 0;
+    const batnaValue = party.batna ?? 0;
+
+    result[party.id] = {
+      dealValue,
+      batnaValue,
+      surplus: round(dealValue - batnaValue, 4)
+    };
+  }
+
+  return result;
+}
+
+function round(value: number, decimals: number): number {
+  const factor = Math.pow(10, decimals);
+  return Math.round(value * factor) / factor;
+}
+
+function roundDimensions(dims: Record<string, number>): Record<string, number> {
+  const result: Record<string, number> = {};
+  for (const [key, value] of Object.entries(dims)) {
+    result[key] = round(value, 4);
+  }
+  return result;
+}
+
+/** Singleton instance */
+export const negotiationStrategy = new NegotiationExecutor();