@higher.archi/boe 1.0.27 → 1.0.29

package/src/engines/negotiation/types.ts

@@ -0,0 +1,244 @@
+/**
+ * Negotiation Engine Types
+ *
+ * Two-party negotiation engine that analyzes zones of possible agreement,
+ * plans concession strategies, and optimizes deal packages across
+ * multiple dimensions.
+ */
+
+import type { SemanticPriority } from '../utility/types';
+
+// ========================================
+// Semantic Types
+// ========================================
+
+/** Negotiation algorithm to use */
+export type NegotiationStrategy = 'zopa-analysis' | 'concession-planning' | 'package-optimization';
+
+/** Concession aggressiveness style */
+export type ConcessionStyle = 'aggressive' | 'moderate' | 'collaborative';
+
+/** Outcome of a negotiation analysis */
+export type DealOutcome = 'agreed' | 'no-zopa' | 'batna-preferred';
+
+/** Whether higher or lower values are preferred for a dimension */
+export type DimensionDirection = 'higher-is-better' | 'lower-is-better';
+
+// ========================================
+// Dimension & Party Types
+// ========================================
+
+/** A single negotiable dimension (e.g. price, delivery time) */
+export type NegotiationDimension = {
+  id: string;
+  name?: string;
+  unit?: string;
+  direction: DimensionDirection;
+};
+
+/** A party's position on a single dimension */
+export type PartyPosition = {
+  dimensionId: string;
+  ideal: number;
+  acceptable: number;
+  walkaway: number;
+};
+
+/** A negotiating party with positions across all dimensions */
+export type PartyProfile = {
+  id: string;
+  name?: string;
+  positions: PartyPosition[];
+  batna?: number;
+};
+
+/** Weight function mapping a dimension to its importance for a party */
+export type ValueFunction = {
+  dimensionId: string;
+  weight: number | SemanticPriority;
+};
+
+// ========================================
+// Compiled Dimension & Party Types
+// ========================================
+
+/** Compiled value function with resolved numeric weight */
+export type CompiledValueFunction = {
+  dimensionId: string;
+  weight: number;           // normalized to sum to 1.0 per party
+};
+
+/** Compiled party profile with resolved weights */
+export type CompiledPartyProfile = {
+  id: string;
+  name?: string;
+  positions: PartyPosition[];
+  batna?: number;
+};
+
+// ========================================
+// Strategy-Specific Config Types
+// ========================================
+
+export type ZopaAnalysisConfig = {
+  resolution?: number;                    // default: 100
+};
+
+export type ConcessionPlanningConfig = {
+  style?: ConcessionStyle;               // default: 'moderate'
+  rounds?: number;                        // default: 5
+  startingPosition?: 'ideal' | 'midpoint'; // default: 'ideal'
+};
+
+export type PackageOptimizationConfig = {
+  sampleSize?: number;                    // default: 1000
+  objectiveWeights?: {
+    closeProb: number;
+    margin: number;
+  };                                      // default: { closeProb: 0.6, margin: 0.4 }
+};
+
+// ========================================
+// Source RuleSet Types (Discriminated Union)
+// ========================================
+
+type NegotiationRuleSetBase = {
+  id: string;
+  name?: string;
+  mode: 'negotiation';
+  dimensions: NegotiationDimension[];
+  parties: [PartyProfile, PartyProfile];
+  valueWeights: Record<string, ValueFunction[]>;
+};
+
+/** ZOPA analysis: compute zones of possible agreement per dimension */
+export type ZopaAnalysisRuleSet = NegotiationRuleSetBase & {
+  strategy: 'zopa-analysis';
+  config?: ZopaAnalysisConfig;
+};
+
+/** Concession planning: simulate round-by-round concession trajectories */
+export type ConcessionPlanningRuleSet = NegotiationRuleSetBase & {
+  strategy: 'concession-planning';
+  config?: ConcessionPlanningConfig;
+};
+
+/** Package optimization: find optimal deal packages within the ZOPA */
+export type PackageOptimizationRuleSet = NegotiationRuleSetBase & {
+  strategy: 'package-optimization';
+  config?: PackageOptimizationConfig;
+};
+
+export type NegotiationRuleSet =
+  | ZopaAnalysisRuleSet
+  | ConcessionPlanningRuleSet
+  | PackageOptimizationRuleSet;
+
+// ========================================
+// Compiled RuleSet Types
+// ========================================
+
+type CompiledNegotiationRuleSetBase = {
+  id: string;
+  name?: string;
+  mode: 'negotiation';
+  dimensions: NegotiationDimension[];
+  parties: [CompiledPartyProfile, CompiledPartyProfile];
+  valueWeights: Record<string, CompiledValueFunction[]>;
+};
+
+export type CompiledZopaAnalysisRuleSet = CompiledNegotiationRuleSetBase & {
+  strategy: 'zopa-analysis';
+  config: {
+    resolution: number;
+  };
+};
+
+export type CompiledConcessionPlanningRuleSet = CompiledNegotiationRuleSetBase & {
+  strategy: 'concession-planning';
+  config: {
+    style: ConcessionStyle;
+    rounds: number;
+    startingPosition: 'ideal' | 'midpoint';
+  };
+};
+
+export type CompiledPackageOptimizationRuleSet = CompiledNegotiationRuleSetBase & {
+  strategy: 'package-optimization';
+  config: {
+    sampleSize: number;
+    objectiveWeights: {
+      closeProb: number;
+      margin: number;
+    };
+  };
+};
+
+export type CompiledNegotiationRuleSet =
+  | CompiledZopaAnalysisRuleSet
+  | CompiledConcessionPlanningRuleSet
+  | CompiledPackageOptimizationRuleSet;
+
+// ========================================
+// Result Types
+// ========================================
+
+/** Range of agreement for a single dimension */
+export type ZopaRange = {
+  dimensionId: string;
+  lower: number;
+  upper: number;
+  size: number;
+};
+
+/** A single round's concession step for one party */
+export type ConcessionStep = {
+  round: number;
+  partyId: string;
+  offers: Record<string, number>;
+  totalValue: number;
+};
+
+/** A candidate deal package */
+export type PackageCandidate = {
+  dimensions: Record<string, number>;
+  partyAValue: number;
+  partyBValue: number;
+  closeProbability: number;
+  marginScore: number;
+  compositeScore: number;
+};
+
+/** Full negotiation result */
+export type NegotiationResult = {
+  outcome: DealOutcome;
+  zopa?: {
+    ranges: ZopaRange[];
+    hasAgreement: boolean;
+    zopaVolume: number;
+  };
+  concessionPlan?: {
+    steps: ConcessionStep[];
+    convergenceRound?: number;
+    finalDeal?: Record<string, number>;
+  };
+  recommendedPackage?: PackageCandidate;
+  allPackages?: PackageCandidate[];
+  batnaComparison: Record<string, {
+    dealValue: number;
+    batnaValue: number;
+    surplus: number;
+  }>;
+  strategy: NegotiationStrategy;
+  executionTimeMs: number;
+};
+
+// ========================================
+// Runtime Types
+// ========================================
+
+/** Runtime options for negotiation execution */
+export type NegotiationOptions = {
+  onStep?: (step: ConcessionStep) => void;
+  onPackage?: (candidate: PackageCandidate) => void;
+};

package/src/index.ts

@@ -32,6 +32,8 @@ export { UtilityEngine } from './engines/utility';
 export { PricingEngine } from './engines/pricing';
 export { EnsembleEngine } from './engines/ensemble';
 export { SentimentEngine } from './engines/sentiment';
+export { NegotiationEngine } from './engines/negotiation';
+export { DecayEngine } from './engines/decay';
 
 // ========================================
 // Core Types & Utilities
@@ -516,6 +518,73 @@ export type {
   IngestResult
 } from './engines/sentiment';
 
+// Negotiation
+export {
+  NegotiationExecutor,
+  compileNegotiationRuleSet,
+  negotiationStrategy
+} from './engines/negotiation';
+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 './engines/negotiation';
+
+// Decay
+export {
+  DecayExecutor,
+  compileDecayRuleSet,
+  decayStrategy,
+  URGENCY_THRESHOLDS,
+  resolveUrgencyTier
+} from './engines/decay';
+export type {
+  DecayStrategy,
+  UrgencyTier,
+  ReEngagementEffect,
+  DecayAggregation,
+  DecayDimension,
+  CompiledDecayDimension,
+  ReEngagementRule,
+  SingleDimensionDecayRuleSet,
+  MultiDimensionDecayRuleSet,
+  EventDrivenDecayRuleSet,
+  DecayRuleSet,
+  CompiledSingleDimensionDecayRuleSet,
+  CompiledMultiDimensionDecayRuleSet,
+  CompiledEventDrivenDecayRuleSet,
+  CompiledDecayRuleSet,
+  DimensionDecayResult,
+  ReEngagementEvent,
+  EntityDecayResult,
+  DecayResult,
+  DecayOptions,
+  DecayIngestResult
+} from './engines/decay';
+
 // ========================================
 // Utility Functions (from old modules, re-exported for convenience)
 // ========================================