@higher.archi/boe 1.0.30 → 1.0.31

package/src/engines/defeasible/types.ts

@@ -36,17 +36,24 @@ import { DecayConfig, DecayInfo } from '../../core/evaluation/decay';
  * - defeasible: Can be defeated by other rules
  * - defeater: Only blocks conclusions, doesn't assert anything
  */
-export type RuleStrength = 'strict' | 'defeasible' | 'defeater';
+export const RuleStrengths = {
+  strict: 'strict',
+  defeasible: 'defeasible',
+  defeater: 'defeater',
+} as const;
+export type RuleStrength = typeof RuleStrengths[keyof typeof RuleStrengths];
 
 /**
  * Conclusion status after evaluation
  */
-export type ConclusionStatus =
-  | 'definitely'      // Proven by strict rule (cannot be defeated)
-  | 'defeasibly'      // Proven by defeasible rule (not currently defeated)
-  | 'defeated'        // Was concluded but defeated by another rule
-  | 'blocked'         // Blocked by a defeater
-  | 'undecided';      // No applicable rules
+export const ConclusionStatuses = {
+  definitely: 'definitely',
+  defeasibly: 'defeasibly',
+  defeated: 'defeated',
+  blocked: 'blocked',
+  undecided: 'undecided',
+} as const;
+export type ConclusionStatus = typeof ConclusionStatuses[keyof typeof ConclusionStatuses];
 
 // ========================================
 // Defeat Strength Types
@@ -55,11 +62,13 @@ export type ConclusionStatus =
 /**
  * Semantic defeat strength labels - human-readable
  */
-export type SemanticDefeatStrength =
-  | 'completely'      // 1.0 - fully defeats
-  | 'strongly'        // 0.85
-  | 'moderately'      // 0.6
-  | 'weakly';         // 0.3
+export const SemanticDefeatStrengths = {
+  completely: 'completely',
+  strongly: 'strongly',
+  moderately: 'moderately',
+  weakly: 'weakly',
+} as const;
+export type SemanticDefeatStrength = typeof SemanticDefeatStrengths[keyof typeof SemanticDefeatStrengths];
 
 /**
  * Semantic strength to numeric mapping
@@ -91,6 +100,12 @@ export type Credibility =
   | 'medium'          // 0.7
   | 'low';            // 0.4
 
+export const SemanticCredibilityLevels = {
+  high: 'high',
+  medium: 'medium',
+  low: 'low',
+} as const;
+
 /**
  * Credibility to numeric mapping
  */
@@ -192,11 +207,20 @@ export type SuperiorityRelation = {
 /**
  * Aggregation strategy for confidence calculation
  */
-export type AggregationStrategy =
-  | 'average'         // Mean of supporters vs mean of attackers
-  | 'max-min'         // Strongest support vs strongest attack
-  | 'weighted-sum'    // Sum with normalization to 0-1
-  | 'probabilistic';  // Independent probability combination
+export const DefeasibleAggregations = {
+  average: 'average',
+  maxMin: 'max-min',
+  weightedSum: 'weighted-sum',
+  probabilistic: 'probabilistic',
+} as const;
+export type AggregationStrategy = typeof DefeasibleAggregations[keyof typeof DefeasibleAggregations];
+
+export const ConflictResolutions = {
+  specificity: 'specificity',
+  priority: 'priority',
+  explicit: 'explicit',
+} as const;
+export type ConflictResolution = typeof ConflictResolutions[keyof typeof ConflictResolutions];
 
 /**
  * Defeasible engine configuration
@@ -222,7 +246,7 @@ export type DefeasibleConfig = {
    * - 'explicit': Only explicit defeats/superiority apply
    * Default: 'specificity'
    */
-  conflictResolution?: 'specificity' | 'priority' | 'explicit';
+  conflictResolution?: ConflictResolution;
 
   /**
    * Maximum iterations for computing defeat cycles (default: 100)

package/src/engines/ensemble/index.ts

@@ -22,6 +22,12 @@ export type {
   EnsembleSummaryOptions
 } from './types';
 
+// Constants
+export {
+  FusionStrategies,
+  AgreementLevels
+} from './types';
+
 // Compiler
 export { compileEnsembleRuleSet } from './compiler';
 

package/src/engines/ensemble/types.ts

@@ -18,13 +18,15 @@ import type { FactInput } from '../../core';
 // Fusion Strategy
 // ========================================
 
-export type FusionStrategy =
-  | 'weighted-average'   // weighted mean of member scores
-  | 'median'             // middle value, robust to outliers
-  | 'min'                // most conservative member score
-  | 'max'                // most optimistic member score
-  | 'voting'             // highest confidence*weight member wins
-  | 'stacking';          // second-layer scoring ruleset over member scores
+export const FusionStrategies = {
+  weightedAverage: 'weighted-average',
+  median: 'median',
+  min: 'min',
+  max: 'max',
+  voting: 'voting',
+  stacking: 'stacking',
+} as const;
+export type FusionStrategy = typeof FusionStrategies[keyof typeof FusionStrategies];
 
 // ========================================
 // Member Definitions (Source)
@@ -123,12 +125,14 @@ export type MemberResult = {
 // ========================================
 
 /** Semantic agreement levels based on coefficient of variation */
-export type AgreementLevel =
-  | 'unanimous'   // agreement = 1.0 (all identical)
-  | 'strong'      // agreement >= 0.90
-  | 'moderate'    // agreement >= 0.70
-  | 'weak'        // agreement >= 0.50
-  | 'divided';    // agreement < 0.50
+export const AgreementLevels = {
+  unanimous: 'unanimous',
+  strong: 'strong',
+  moderate: 'moderate',
+  weak: 'weak',
+  divided: 'divided',
+} as const;
+export type AgreementLevel = typeof AgreementLevels[keyof typeof AgreementLevels];
 
 /** Ensemble result — mirrors ScoringResult shape for downstream compatibility */
 export type EnsembleResult<T extends TierDefinition = TierDefinition> = {

package/src/engines/expert/index.ts

@@ -32,6 +32,7 @@
 // Types
 export {
   // Semantic confidence
+  SemanticConfidences,
   SemanticConfidence,
   SEMANTIC_CONFIDENCES,
   Confidence,

package/src/engines/expert/types.ts

@@ -32,15 +32,17 @@ import {
  * Semantic confidence labels for human-readable rule authoring.
  * Maps to numeric values between 0.0 and 1.0.
  */
-export type SemanticConfidence =
-  | 'certain'     // 1.0 - Absolute certainty (e.g., mathematical facts)
-  | 'very-high'   // 0.95 - Near certain (e.g., well-established patterns)
-  | 'high'        // 0.85 - Strong confidence (e.g., clear evidence)
-  | 'likely'      // 0.75 - Probable (e.g., good indicators)
-  | 'moderate'    // 0.65 - Moderate confidence (e.g., partial evidence)
-  | 'possible'    // 0.50 - Even odds (e.g., uncertain)
-  | 'unlikely'    // 0.35 - Improbable (e.g., weak evidence)
-  | 'low';        // 0.20 - Low confidence (e.g., minimal support)
+export const SemanticConfidences = {
+  certain: 'certain',
+  veryHigh: 'very-high',
+  high: 'high',
+  likely: 'likely',
+  moderate: 'moderate',
+  possible: 'possible',
+  unlikely: 'unlikely',
+  low: 'low',
+} as const;
+export type SemanticConfidence = typeof SemanticConfidences[keyof typeof SemanticConfidences];
 
 /**
  * Mapping from semantic labels to numeric confidence values.

package/src/engines/fuzzy/fuzzy.types.ts

@@ -15,22 +15,48 @@ import { BindingContext } from '../../core';
  * Membership function shapes
  * These define how membership degree (0-1) is calculated from a crisp value
  */
-export type MembershipShape = 'triangle' | 'trapezoid' | 'gaussian' | 'shoulder' | 'block';
+export const MembershipShapes = {
+  triangle: 'triangle',
+  trapezoid: 'trapezoid',
+  gaussian: 'gaussian',
+  shoulder: 'shoulder',
+  block: 'block',
+} as const;
+export type MembershipShape = typeof MembershipShapes[keyof typeof MembershipShapes];
 
 /**
  * Semantic position within domain (compiles to numeric center)
  */
-export type PositionSemantic = 'very-low' | 'low' | 'medium' | 'high' | 'very-high';
+export const PositionSemantics = {
+  veryLow: 'very-low',
+  low: 'low',
+  medium: 'medium',
+  high: 'high',
+  veryHigh: 'very-high',
+} as const;
+export type PositionSemantic = typeof PositionSemantics[keyof typeof PositionSemantics];
 
 /**
  * Semantic width/spread (compiles to numeric spread as % of domain)
  */
-export type WidthSemantic = 'tight' | 'narrow' | 'medium' | 'wide' | 'very-wide';
+export const WidthSemantics = {
+  tight: 'tight',
+  narrow: 'narrow',
+  medium: 'medium',
+  wide: 'wide',
+  veryWide: 'very-wide',
+} as const;
+export type WidthSemantic = typeof WidthSemantics[keyof typeof WidthSemantics];
 
 /**
  * Edge behavior for shoulder/block shapes
  */
-export type EdgeSemantic = 'open-left' | 'open-right' | 'closed';
+export const EdgeSemantics = {
+  openLeft: 'open-left',
+  openRight: 'open-right',
+  closed: 'closed',
+} as const;
+export type EdgeSemantic = typeof EdgeSemantics[keyof typeof EdgeSemantics];
 
 // ========================================
 // Fuzzy Term Definitions
@@ -127,33 +153,39 @@ export type CompiledFuzzyVariable = {
 /**
  * Aggregation methods - combine multiple rule activations for same output
  */
-export type AggregationMethod =
-  | 'max'     // Maximum membership (standard fuzzy OR)
-  | 'sum'     // Sum memberships (can exceed 1)
-  | 'probor'  // Probabilistic OR: a + b - ab
-  | 'bound'   // Bounded sum: min(1, a + b)
-  | 'min';    // Intersection (rare)
+export const AggregationMethods = {
+  max: 'max',
+  sum: 'sum',
+  probor: 'probor',
+  bound: 'bound',
+  min: 'min',
+} as const;
+export type AggregationMethod = typeof AggregationMethods[keyof typeof AggregationMethods];
 
 /**
  * Defuzzification methods - convert fuzzy output to crisp value
  */
-export type DefuzzifyMethod =
-  | 'centroid'  // Center of gravity (most common)
-  | 'bisector'  // Line that divides area in half
-  | 'mom'       // Mean of maximum
-  | 'som'       // Smallest of maximum
-  | 'lom'       // Largest of maximum
-  | 'wtaver';   // Weighted average of term centers
+export const DefuzzifyMethods = {
+  centroid: 'centroid',
+  bisector: 'bisector',
+  mom: 'mom',
+  som: 'som',
+  lom: 'lom',
+  wtaver: 'wtaver',
+} as const;
+export type DefuzzifyMethod = typeof DefuzzifyMethods[keyof typeof DefuzzifyMethods];
 
 /**
  * Transform methods - post-process the crisp output
  */
-export type TransformMethod =
-  | 'clamp'     // Enforce output bounds
-  | 'round'     // Round to integer
-  | 'deadband'  // Zero out small values
-  | 'scale'     // Scale to different range
-  | 'quantize'; // Snap to discrete steps
+export const TransformMethods = {
+  clamp: 'clamp',
+  round: 'round',
+  deadband: 'deadband',
+  scale: 'scale',
+  quantize: 'quantize',
+} as const;
+export type TransformMethod = typeof TransformMethods[keyof typeof TransformMethods];
 
 /**
  * Any defuzzification pipeline stage
@@ -163,14 +195,16 @@ export type DefuzzifyStage = AggregationMethod | DefuzzifyMethod | TransformMeth
 /**
  * Named presets that expand to full pipelines
  */
-export type DefuzzifyPreset =
-  | 'balanced'    // ['max', 'centroid', 'clamp'] - general purpose
-  | 'smooth'      // ['probor', 'centroid', 'clamp'] - gradual transitions
-  | 'decisive'    // ['max', 'mom'] - snappy response
-  | 'cautious'    // ['max', 'som', 'clamp'] - conservative
-  | 'aggressive'  // ['max', 'lom', 'clamp'] - responsive
-  | 'discrete'    // ['max', 'centroid', 'clamp', 'round'] - integer outputs
-  | 'stable';     // ['max', 'centroid', 'deadband', 'clamp'] - reduce chatter
+export const DefuzzifyPresets = {
+  balanced: 'balanced',
+  smooth: 'smooth',
+  decisive: 'decisive',
+  cautious: 'cautious',
+  aggressive: 'aggressive',
+  discrete: 'discrete',
+  stable: 'stable',
+} as const;
+export type DefuzzifyPreset = typeof DefuzzifyPresets[keyof typeof DefuzzifyPresets];
 
 /**
  * Defuzzification pipeline configuration

package/src/engines/loyalty/index.ts

@@ -33,6 +33,15 @@ export type {
   LoyaltyIngestResult
 } from './types';
 
+// Constants
+export {
+  LoyaltyStrategies,
+  PointTransactionTypes,
+  TierStatuses,
+  QualifyingMetrics,
+  EvaluationPeriods
+} from './types';
+
 // Compiler
 export { compileLoyaltyRuleSet } from './compiler';
 

package/src/engines/loyalty/types.ts

@@ -14,19 +14,50 @@ import type { Condition } from '../../core/types/condition';
 // ========================================
 
 /** Loyalty strategy to use */
-export type LoyaltyStrategy = 'earning' | 'redemption' | 'tier-evaluation';
+export const LoyaltyStrategies = {
+  earning: 'earning',
+  redemption: 'redemption',
+  tierEvaluation: 'tier-evaluation',
+} as const;
+export type LoyaltyStrategy = typeof LoyaltyStrategies[keyof typeof LoyaltyStrategies];
 
 /** Point transaction type */
-export type PointTransactionType = 'earn' | 'redeem' | 'expire' | 'transfer' | 'adjust';
+export const PointTransactionTypes = {
+  earn: 'earn',
+  redeem: 'redeem',
+  expire: 'expire',
+  transfer: 'transfer',
+  adjust: 'adjust',
+} as const;
+export type PointTransactionType = typeof PointTransactionTypes[keyof typeof PointTransactionTypes];
 
 /** Member tier status */
-export type TierStatus = 'qualified' | 'at-risk' | 'downgrade-pending' | 'locked';
+export const TierStatuses = {
+  qualified: 'qualified',
+  atRisk: 'at-risk',
+  downgradePending: 'downgrade-pending',
+  locked: 'locked',
+} as const;
+export type TierStatus = typeof TierStatuses[keyof typeof TierStatuses];
 
 /** Qualifying metric for tier evaluation */
-export type QualifyingMetric = 'points-earned' | 'qualifying-spend' | 'qualifying-nights' | 'qualifying-flights';
+export const QualifyingMetrics = {
+  pointsEarned: 'points-earned',
+  qualifyingSpend: 'qualifying-spend',
+  qualifyingNights: 'qualifying-nights',
+  qualifyingFlights: 'qualifying-flights',
+  qualifyingRentalDays: 'qualifying-rental-days',
+  qualifyingCruiseDays: 'qualifying-cruise-days',
+} as const;
+export type QualifyingMetric = typeof QualifyingMetrics[keyof typeof QualifyingMetrics];
 
 /** Evaluation period for tier assessment */
-export type EvaluationPeriod = 'rolling-12-months' | 'calendar-year' | 'custom';
+export const EvaluationPeriods = {
+  rolling12Months: 'rolling-12-months',
+  calendarYear: 'calendar-year',
+  custom: 'custom',
+} as const;
+export type EvaluationPeriod = typeof EvaluationPeriods[keyof typeof EvaluationPeriods];
 
 // ========================================
 // Core Domain Types

package/src/engines/menu-engineering/compiler.ts

@@ -0,0 +1,145 @@
+/**
+ * Menu Engineering Engine Compiler
+ *
+ * Validates menu engineering rulesets and resolves defaults.
+ */
+
+import { CompilationError } from '../../core/errors';
+
+import type {
+  MenuEngineeringRuleSet,
+  CompiledMenuEngineeringRuleSet,
+  CompiledClassifyRuleSet,
+  CompiledPriceOptimizationRuleSet,
+  CompiledMixAnalysisRuleSet
+} from './types';
+
+/**
+ * Compile and validate a menu engineering ruleset.
+ */
+export function compileMenuEngineeringRuleSet(
+  ruleSet: MenuEngineeringRuleSet
+): CompiledMenuEngineeringRuleSet {
+  if (!ruleSet.id) {
+    throw new CompilationError('Menu engineering ruleset requires an id');
+  }
+
+  if (ruleSet.mode !== 'menu-engineering') {
+    throw new CompilationError(`Expected mode 'menu-engineering', got '${ruleSet.mode}'`);
+  }
+
+  if (!ruleSet.items || ruleSet.items.length === 0) {
+    throw new CompilationError('Menu engineering ruleset requires at least one menu item');
+  }
+
+  // Validate unique item IDs
+  const itemIds = new Set<string>();
+  for (const item of ruleSet.items) {
+    if (!item.id) {
+      throw new CompilationError('Each menu item requires an id');
+    }
+    if (itemIds.has(item.id)) {
+      throw new CompilationError(`Duplicate menu item id: '${item.id}'`);
+    }
+    if (item.sellingPrice < 0) {
+      throw new CompilationError(`Menu item '${item.id}' sellingPrice must be non-negative`);
+    }
+    if (item.plateCost < 0) {
+      throw new CompilationError(`Menu item '${item.id}' plateCost must be non-negative`);
+    }
+    if (item.salesCount < 0) {
+      throw new CompilationError(`Menu item '${item.id}' salesCount must be non-negative`);
+    }
+    itemIds.add(item.id);
+  }
+
+  switch (ruleSet.strategy) {
+    case 'classify':
+      return compileClassify(ruleSet);
+    case 'price-optimization':
+      return compilePriceOptimization(ruleSet);
+    case 'mix-analysis':
+      return compileMixAnalysis(ruleSet);
+    default:
+      throw new CompilationError(`Unknown menu engineering strategy: '${(ruleSet as any).strategy}'`);
+  }
+}
+
+function compileClassify(
+  ruleSet: MenuEngineeringRuleSet & { strategy: 'classify' }
+): CompiledClassifyRuleSet {
+  const config = ruleSet.config ?? {};
+
+  return {
+    id: ruleSet.id,
+    name: ruleSet.name,
+    mode: 'menu-engineering',
+    strategy: 'classify',
+    items: ruleSet.items,
+    config: {
+      mixThresholdMode: config.mixThresholdMode ?? 'average',
+      customMixThreshold: config.customMixThreshold ?? 0,
+      marginThresholdMode: config.marginThresholdMode ?? 'average',
+      customMarginThreshold: config.customMarginThreshold ?? 0
+    }
+  };
+}
+
+function compilePriceOptimization(
+  ruleSet: MenuEngineeringRuleSet & { strategy: 'price-optimization' }
+): CompiledPriceOptimizationRuleSet {
+  if (!ruleSet.config || !ruleSet.config.priceChanges || ruleSet.config.priceChanges.length === 0) {
+    throw new CompilationError('Price-optimization strategy requires at least one price change');
+  }
+
+  // Validate price changes reference existing items
+  const itemIds = new Set(ruleSet.items.map(i => i.id));
+  for (const change of ruleSet.config.priceChanges) {
+    if (!itemIds.has(change.itemId)) {
+      throw new CompilationError(`Price change references unknown item: '${change.itemId}'`);
+    }
+    if (change.newPrice < 0) {
+      throw new CompilationError(`Price change for '${change.itemId}' newPrice must be non-negative`);
+    }
+  }
+
+  return {
+    id: ruleSet.id,
+    name: ruleSet.name,
+    mode: 'menu-engineering',
+    strategy: 'price-optimization',
+    items: ruleSet.items,
+    config: {
+      priceChanges: ruleSet.config.priceChanges,
+      elasticities: ruleSet.config.elasticities ?? [],
+      defaultElasticity: ruleSet.config.defaultElasticity ?? -1.0
+    }
+  };
+}
+
+function compileMixAnalysis(
+  ruleSet: MenuEngineeringRuleSet & { strategy: 'mix-analysis' }
+): CompiledMixAnalysisRuleSet {
+  const config = ruleSet.config ?? {};
+  const groupBy = config.groupBy ?? 'category';
+
+  if (groupBy === 'category') {
+    // Verify at least some items have categories
+    const hasCategories = ruleSet.items.some(i => i.category);
+    if (!hasCategories) {
+      throw new CompilationError('Mix-analysis with groupBy "category" requires items with category values');
+    }
+  }
+
+  return {
+    id: ruleSet.id,
+    name: ruleSet.name,
+    mode: 'menu-engineering',
+    strategy: 'mix-analysis',
+    items: ruleSet.items,
+    config: {
+      groupBy,
+      daypartField: config.daypartField ?? 'daypart'
+    }
+  };
+}

package/src/engines/menu-engineering/engine.ts

@@ -0,0 +1,48 @@
+/**
+ * Menu Engineering Engine
+ *
+ * Classifies menu items into Stars/Plowhorses/Puzzles/Dogs based on
+ * sales mix percentage and contribution margin. Supports price optimization
+ * with elasticity modeling and category-level mix analysis.
+ *
+ * @example
+ * ```typescript
+ * const engine = new MenuEngineeringEngine();
+ *
+ * const result = engine.execute(compiledMenuEngineering);
+ * // result.items -> classified menu items with recommendations
+ * ```
+ */
+
+import type {
+  CompiledMenuEngineeringRuleSet,
+  MenuEngineeringOptions,
+  MenuEngineeringResult
+} from './types';
+
+import { MenuEngineeringExecutor } from './strategy';
+
+export class MenuEngineeringEngine {
+  private strategy: MenuEngineeringExecutor;
+
+  constructor() {
+    this.strategy = new MenuEngineeringExecutor();
+  }
+
+  /**
+   * Execute a menu engineering ruleset.
+   *
+   * Classifies menu items, optimizes prices, or analyzes category mix
+   * depending on the strategy.
+   *
+   * @param ruleSet - Compiled menu engineering ruleset
+   * @param options - Runtime options
+   * @returns Menu engineering result
+   */
+  execute(
+    ruleSet: CompiledMenuEngineeringRuleSet,
+    options: MenuEngineeringOptions = {}
+  ): MenuEngineeringResult {
+    return this.strategy.run(ruleSet, options);
+  }
+}

package/src/engines/menu-engineering/index.ts

@@ -0,0 +1,47 @@
+/**
+ * Menu Engineering Engine -- Menu Item Classification & Optimization
+ */
+
+// Types
+export type {
+  MenuEngineeringStrategy,
+  MenuClassification,
+  MenuItem,
+  PriceElasticity,
+  PriceChange,
+  ClassifyConfig,
+  PriceOptimizationConfig,
+  MixAnalysisConfig,
+  ClassifyRuleSet,
+  PriceOptimizationRuleSet,
+  MixAnalysisRuleSet,
+  MenuEngineeringRuleSet,
+  CompiledClassifyRuleSet,
+  CompiledPriceOptimizationRuleSet,
+  CompiledMixAnalysisRuleSet,
+  CompiledMenuEngineeringRuleSet,
+  ClassifiedItem,
+  MenuSummary,
+  PriceOptimizationItem,
+  CategoryMixResult,
+  ClassifyResult,
+  PriceOptimizationResult,
+  MixAnalysisResult,
+  MenuEngineeringResult,
+  MenuEngineeringOptions
+} from './types';
+
+// Constants
+export {
+  MenuEngineeringStrategies,
+  MenuClassifications
+} from './types';
+
+// Compiler
+export { compileMenuEngineeringRuleSet } from './compiler';
+
+// Strategy
+export { MenuEngineeringExecutor, menuEngineeringStrategy } from './strategy';
+
+// Engine
+export { MenuEngineeringEngine } from './engine';