@higher.archi/boe 1.0.27 → 1.0.29

package/src/engines/negotiation/compiler.ts

@@ -0,0 +1,229 @@
+/**
+ * Negotiation Engine Compiler
+ *
+ * Validates negotiation rulesets and resolves defaults.
+ */
+
+import { CompilationError } from '../../core/errors';
+import { SEMANTIC_PRIORITY_VALUES, isSemanticPriority, type SemanticPriority } from '../utility/types';
+
+import type {
+  NegotiationRuleSet,
+  CompiledNegotiationRuleSet,
+  CompiledZopaAnalysisRuleSet,
+  CompiledConcessionPlanningRuleSet,
+  CompiledPackageOptimizationRuleSet,
+  CompiledValueFunction,
+  CompiledPartyProfile,
+  ValueFunction
+} from './types';
+
+/**
+ * Compile and validate a negotiation ruleset.
+ */
+export function compileNegotiationRuleSet(
+  ruleSet: NegotiationRuleSet
+): CompiledNegotiationRuleSet {
+  if (!ruleSet.id) {
+    throw new CompilationError('Negotiation ruleset requires an id');
+  }
+
+  if (ruleSet.mode !== 'negotiation') {
+    throw new CompilationError(`Expected mode 'negotiation', got '${ruleSet.mode}'`);
+  }
+
+  // Validate dimensions
+  if (!ruleSet.dimensions || ruleSet.dimensions.length === 0) {
+    throw new CompilationError('At least one dimension is required');
+  }
+
+  const dimensionIds = new Set<string>();
+  for (const dim of ruleSet.dimensions) {
+    if (!dim.id) {
+      throw new CompilationError('Each dimension requires an id');
+    }
+    if (dimensionIds.has(dim.id)) {
+      throw new CompilationError(`Duplicate dimension id: '${dim.id}'`);
+    }
+    dimensionIds.add(dim.id);
+  }
+
+  // Validate exactly 2 parties
+  if (!ruleSet.parties || ruleSet.parties.length !== 2) {
+    throw new CompilationError('Exactly 2 parties are required');
+  }
+
+  // Validate party positions reference existing dimensions and ordering
+  for (const party of ruleSet.parties) {
+    if (!party.id) {
+      throw new CompilationError('Each party requires an id');
+    }
+
+    for (const pos of party.positions) {
+      if (!dimensionIds.has(pos.dimensionId)) {
+        throw new CompilationError(
+          `Party '${party.id}' references unknown dimension '${pos.dimensionId}'`
+        );
+      }
+
+      // Validate acceptable is between ideal and walkaway
+      // Each party can have any direction preference -- the dimension direction
+      // represents party A's preference, party B naturally has the opposite.
+      const minVal = Math.min(pos.ideal, pos.walkaway);
+      const maxVal = Math.max(pos.ideal, pos.walkaway);
+      if (pos.acceptable < minVal || pos.acceptable > maxVal) {
+        throw new CompilationError(
+          `Party '${party.id}', dimension '${pos.dimensionId}': ` +
+          `acceptable must be between ideal and walkaway`
+        );
+      }
+      if (pos.ideal === pos.walkaway) {
+        throw new CompilationError(
+          `Party '${party.id}', dimension '${pos.dimensionId}': ` +
+          `ideal and walkaway must differ`
+        );
+      }
+    }
+  }
+
+  // Resolve and normalize value weights per party
+  const compiledWeights: Record<string, CompiledValueFunction[]> = {};
+
+  for (const partyId of Object.keys(ruleSet.valueWeights)) {
+    const weights = ruleSet.valueWeights[partyId];
+    const resolved = resolveWeights(weights, partyId);
+    compiledWeights[partyId] = resolved;
+  }
+
+  // Build compiled parties
+  const compiledParties: [CompiledPartyProfile, CompiledPartyProfile] = [
+    {
+      id: ruleSet.parties[0].id,
+      name: ruleSet.parties[0].name,
+      positions: ruleSet.parties[0].positions,
+      batna: ruleSet.parties[0].batna
+    },
+    {
+      id: ruleSet.parties[1].id,
+      name: ruleSet.parties[1].name,
+      positions: ruleSet.parties[1].positions,
+      batna: ruleSet.parties[1].batna
+    }
+  ];
+
+  switch (ruleSet.strategy) {
+    case 'zopa-analysis':
+      return compileZopaAnalysis(ruleSet, compiledParties, compiledWeights);
+    case 'concession-planning':
+      return compileConcessionPlanning(ruleSet, compiledParties, compiledWeights);
+    case 'package-optimization':
+      return compilePackageOptimization(ruleSet, compiledParties, compiledWeights);
+    default:
+      throw new CompilationError(`Unknown negotiation strategy: '${(ruleSet as any).strategy}'`);
+  }
+}
+
+// ========================================
+// Strategy-Specific Compilers
+// ========================================
+
+function compileZopaAnalysis(
+  ruleSet: NegotiationRuleSet & { strategy: 'zopa-analysis' },
+  parties: [CompiledPartyProfile, CompiledPartyProfile],
+  valueWeights: Record<string, CompiledValueFunction[]>
+): CompiledZopaAnalysisRuleSet {
+  return {
+    id: ruleSet.id,
+    name: ruleSet.name,
+    mode: 'negotiation',
+    strategy: 'zopa-analysis',
+    dimensions: ruleSet.dimensions,
+    parties,
+    valueWeights,
+    config: {
+      resolution: ruleSet.config?.resolution ?? 100
+    }
+  };
+}
+
+function compileConcessionPlanning(
+  ruleSet: NegotiationRuleSet & { strategy: 'concession-planning' },
+  parties: [CompiledPartyProfile, CompiledPartyProfile],
+  valueWeights: Record<string, CompiledValueFunction[]>
+): CompiledConcessionPlanningRuleSet {
+  return {
+    id: ruleSet.id,
+    name: ruleSet.name,
+    mode: 'negotiation',
+    strategy: 'concession-planning',
+    dimensions: ruleSet.dimensions,
+    parties,
+    valueWeights,
+    config: {
+      style: ruleSet.config?.style ?? 'moderate',
+      rounds: ruleSet.config?.rounds ?? 5,
+      startingPosition: ruleSet.config?.startingPosition ?? 'ideal'
+    }
+  };
+}
+
+function compilePackageOptimization(
+  ruleSet: NegotiationRuleSet & { strategy: 'package-optimization' },
+  parties: [CompiledPartyProfile, CompiledPartyProfile],
+  valueWeights: Record<string, CompiledValueFunction[]>
+): CompiledPackageOptimizationRuleSet {
+  return {
+    id: ruleSet.id,
+    name: ruleSet.name,
+    mode: 'negotiation',
+    strategy: 'package-optimization',
+    dimensions: ruleSet.dimensions,
+    parties,
+    valueWeights,
+    config: {
+      sampleSize: ruleSet.config?.sampleSize ?? 1000,
+      objectiveWeights: ruleSet.config?.objectiveWeights ?? {
+        closeProb: 0.6,
+        margin: 0.4
+      }
+    }
+  };
+}
+
+// ========================================
+// Weight Resolution
+// ========================================
+
+function resolveWeights(
+  weights: ValueFunction[],
+  partyId: string
+): CompiledValueFunction[] {
+  const resolved: CompiledValueFunction[] = weights.map(w => {
+    let weight: number;
+    if (isSemanticPriority(w.weight)) {
+      weight = SEMANTIC_PRIORITY_VALUES[w.weight as SemanticPriority];
+    } else if (typeof w.weight === 'number') {
+      weight = w.weight;
+    } else {
+      throw new CompilationError(
+        `Invalid weight for party '${partyId}', dimension '${w.dimensionId}': '${w.weight}'`
+      );
+    }
+
+    return {
+      dimensionId: w.dimensionId,
+      weight
+    };
+  });
+
+  // Normalize to sum to 1.0
+  const totalWeight = resolved.reduce((sum, w) => sum + w.weight, 0);
+  if (totalWeight === 0) {
+    throw new CompilationError(`Value weights for party '${partyId}' must not all be zero`);
+  }
+  for (const w of resolved) {
+    w.weight = w.weight / totalWeight;
+  }
+
+  return resolved;
+}

package/src/engines/negotiation/engine.ts

@@ -0,0 +1,117 @@
+/**
+ * Negotiation Engine
+ *
+ * Two-party negotiation engine that analyzes zones of possible agreement,
+ * plans concession strategies, and optimizes deal packages across
+ * multiple dimensions.
+ *
+ * @example
+ * ```typescript
+ * const engine = new NegotiationEngine();
+ *
+ * const result = engine.execute(compiledNegotiation);
+ * console.log(result.outcome); // 'agreed' | 'no-zopa' | 'batna-preferred'
+ * ```
+ */
+
+import {
+  WorkingMemory,
+  Fact,
+  FactInput,
+  FactChange
+} from '../../core';
+
+import type {
+  CompiledNegotiationRuleSet,
+  NegotiationOptions,
+  NegotiationResult
+} from './types';
+
+import { NegotiationExecutor } from './strategy';
+
+export class NegotiationEngine {
+  private wm: WorkingMemory;
+  private strategy: NegotiationExecutor;
+
+  constructor(workingMemory?: WorkingMemory) {
+    this.wm = workingMemory ?? new WorkingMemory();
+    this.strategy = new NegotiationExecutor();
+  }
+
+  // ========================================
+  // IWorkingMemory Implementation
+  // ========================================
+
+  add<T = Record<string, any>>(input: FactInput<T>): Fact<T> {
+    return this.wm.add(input);
+  }
+
+  remove(factId: string): Fact | undefined {
+    return this.wm.remove(factId);
+  }
+
+  update<T = Record<string, any>>(input: FactInput<T>): Fact<T> {
+    return this.wm.update(input);
+  }
+
+  get(factId: string): Fact | undefined {
+    return this.wm.get(factId);
+  }
+
+  getByType(type: string): Fact[] {
+    return this.wm.getByType(type);
+  }
+
+  getAll(): Fact[] {
+    return this.wm.getAll();
+  }
+
+  has(factId: string): boolean {
+    return this.wm.has(factId);
+  }
+
+  size(): number {
+    return this.wm.size();
+  }
+
+  clear(): void {
+    this.wm.clear();
+  }
+
+  getChanges(): FactChange[] {
+    return this.wm.getChanges();
+  }
+
+  clearChanges(): void {
+    this.wm.clearChanges();
+  }
+
+  // ========================================
+  // Engine Execution
+  // ========================================
+
+  /**
+   * Execute a negotiation ruleset.
+   *
+   * Analyzes party positions across all dimensions and produces
+   * a negotiation result with ZOPA, concession plans, or optimized packages.
+   *
+   * @param ruleSet - Compiled negotiation ruleset
+   * @param options - Runtime options (onStep callback, onPackage callback)
+   * @returns Negotiation result with outcome and analysis
+   */
+  execute(
+    ruleSet: CompiledNegotiationRuleSet,
+    options: NegotiationOptions = {}
+  ): NegotiationResult {
+    return this.strategy.run(ruleSet, options);
+  }
+
+  // ========================================
+  // Utility Methods
+  // ========================================
+
+  getWorkingMemory(): WorkingMemory {
+    return this.wm;
+  }
+}

package/src/engines/negotiation/index.ts

@@ -0,0 +1,42 @@
+/**
+ * Negotiation Engine -- Two-Party Deal Analysis
+ */
+
+// Types
+export type {
+  NegotiationStrategy,
+  ConcessionStyle,
+  DealOutcome,
+  DimensionDirection,
+  NegotiationDimension,
+  PartyPosition,
+  PartyProfile,
+  ValueFunction,
+  CompiledValueFunction,
+  CompiledPartyProfile,
+  ZopaAnalysisConfig,
+  ConcessionPlanningConfig,
+  PackageOptimizationConfig,
+  ZopaAnalysisRuleSet,
+  ConcessionPlanningRuleSet,
+  PackageOptimizationRuleSet,
+  NegotiationRuleSet,
+  CompiledZopaAnalysisRuleSet,
+  CompiledConcessionPlanningRuleSet,
+  CompiledPackageOptimizationRuleSet,
+  CompiledNegotiationRuleSet,
+  ZopaRange,
+  ConcessionStep,
+  PackageCandidate,
+  NegotiationResult,
+  NegotiationOptions
+} from './types';
+
+// Compiler
+export { compileNegotiationRuleSet } from './compiler';
+
+// Strategy
+export { NegotiationExecutor, negotiationStrategy } from './strategy';
+
+// Engine
+export { NegotiationEngine } from './engine';