@higher.archi/boe 1.0.30 → 1.0.31

package/src/engines/monte-carlo/types.ts

@@ -59,27 +59,22 @@ export const ITERATION_PRESETS: Record<IterationPreset, number> = {
  * Estimate type determines the probability distribution shape.
  * Multiple aliases supported for different audiences.
  */
-export type EstimateType =
-  // Triangular distribution (three-point estimate)
-  | 'best-likely-worst'           // Project management terminology
-  | 'low-mid-high'                // Simple/casual
-  | 'min-expected-max'            // Statistical terminology
-  | 'optimistic-realistic-pessimistic'  // Risk analysis terminology
-
-  // Normal distribution (bell curve)
-  | 'typically-around'            // Layperson-friendly
-  | 'bell-curve'                  // Technical
-  | 'normal'                      // Statistical
-
-  // Uniform distribution (equal probability)
-  | 'anywhere-from'               // Layperson-friendly
-  | 'uniform'                     // Technical
-  | 'any-between'                 // Alternative
-
-  // Discrete distribution (weighted choices)
-  | 'one-of'                      // Layperson-friendly
-  | 'weighted'                    // Technical
-  | 'choice';                     // Alternative
+export const EstimateTypes = {
+  bestLikelyWorst: 'best-likely-worst',
+  lowMidHigh: 'low-mid-high',
+  minExpectedMax: 'min-expected-max',
+  optimisticRealisticPessimistic: 'optimistic-realistic-pessimistic',
+  typicallyAround: 'typically-around',
+  bellCurve: 'bell-curve',
+  normal: 'normal',
+  anywhereFrom: 'anywhere-from',
+  uniform: 'uniform',
+  anyBetween: 'any-between',
+  oneOf: 'one-of',
+  weighted: 'weighted',
+  choice: 'choice',
+} as const;
+export type EstimateType = typeof EstimateTypes[keyof typeof EstimateTypes];
 
 // ========================================
 // Variable Definitions

package/src/engines/negotiation/index.ts

@@ -32,6 +32,14 @@ export type {
   NegotiationOptions
 } from './types';
 
+// Constants
+export {
+  NegotiationStrategies,
+  ConcessionStyles,
+  DealOutcomes,
+  DimensionDirections
+} from './types';
+
 // Compiler
 export { compileNegotiationRuleSet } from './compiler';
 

package/src/engines/negotiation/types.ts

@@ -13,16 +13,35 @@ import type { SemanticPriority } from '../utility/types';
 // ========================================
 
 /** Negotiation algorithm to use */
-export type NegotiationStrategy = 'zopa-analysis' | 'concession-planning' | 'package-optimization';
+export const NegotiationStrategies = {
+  zopaAnalysis: 'zopa-analysis',
+  concessionPlanning: 'concession-planning',
+  packageOptimization: 'package-optimization',
+} as const;
+export type NegotiationStrategy = typeof NegotiationStrategies[keyof typeof NegotiationStrategies];
 
 /** Concession aggressiveness style */
-export type ConcessionStyle = 'aggressive' | 'moderate' | 'collaborative';
+export const ConcessionStyles = {
+  aggressive: 'aggressive',
+  moderate: 'moderate',
+  collaborative: 'collaborative',
+} as const;
+export type ConcessionStyle = typeof ConcessionStyles[keyof typeof ConcessionStyles];
 
 /** Outcome of a negotiation analysis */
-export type DealOutcome = 'agreed' | 'no-zopa' | 'batna-preferred';
+export const DealOutcomes = {
+  agreed: 'agreed',
+  noZopa: 'no-zopa',
+  batnaPreferred: 'batna-preferred',
+} as const;
+export type DealOutcome = typeof DealOutcomes[keyof typeof DealOutcomes];
 
 /** Whether higher or lower values are preferred for a dimension */
-export type DimensionDirection = 'higher-is-better' | 'lower-is-better';
+export const DimensionDirections = {
+  higherIsBetter: 'higher-is-better',
+  lowerIsBetter: 'lower-is-better',
+} as const;
+export type DimensionDirection = typeof DimensionDirections[keyof typeof DimensionDirections];
 
 // ========================================
 // Dimension & Party Types

package/src/engines/prediction/index.ts

@@ -31,6 +31,11 @@ export type {
 
 // Constants & utilities
 export {
+  PredictionStrategies,
+  TrendDirections,
+  SmoothingPresets,
+  HorizonPresets,
+  ConfidenceBrackets,
   SMOOTHING_PRESET_VALUES,
   HORIZON_PRESET_VALUES,
   isSmoothingPreset,

package/src/engines/prediction/types.ts

@@ -11,19 +11,49 @@
 // ========================================
 
 /** Prediction algorithm to use */
-export type PredictionStrategy = 'linear-regression' | 'exponential-smoothing' | 'weighted-moving-average';
+export const PredictionStrategies = {
+  linearRegression: 'linear-regression',
+  exponentialSmoothing: 'exponential-smoothing',
+  weightedMovingAverage: 'weighted-moving-average',
+} as const;
+export type PredictionStrategy = typeof PredictionStrategies[keyof typeof PredictionStrategies];
 
 /** Trend direction derived from slope */
-export type TrendDirection = 'rising' | 'stable' | 'declining' | 'insufficient-data';
+export const TrendDirections = {
+  rising: 'rising',
+  stable: 'stable',
+  declining: 'declining',
+  insufficientData: 'insufficient-data',
+} as const;
+export type TrendDirection = typeof TrendDirections[keyof typeof TrendDirections];
 
 /** Exponential smoothing sensitivity presets */
-export type SmoothingPreset = 'responsive' | 'balanced' | 'smooth';
+export const SmoothingPresets = {
+  responsive: 'responsive',
+  balanced: 'balanced',
+  smooth: 'smooth',
+} as const;
+export type SmoothingPreset = typeof SmoothingPresets[keyof typeof SmoothingPresets];
 
 /** Forecast horizon presets */
-export type HorizonPreset = '1-day' | '1-week' | '1-month' | '3-months' | '6-months' | '1-year';
+export const HorizonPresets = {
+  oneDay: '1-day',
+  oneWeek: '1-week',
+  oneMonth: '1-month',
+  threeMonths: '3-months',
+  sixMonths: '6-months',
+  oneYear: '1-year',
+} as const;
+export type HorizonPreset = typeof HorizonPresets[keyof typeof HorizonPresets];
 
 /** Human-readable confidence bracket */
-export type ConfidenceBracket = 'high' | 'moderate' | 'low' | 'insufficient-data';
+export const ConfidenceBrackets = {
+  high: 'high',
+  moderate: 'moderate',
+  low: 'low',
+  insufficientData: 'insufficient-data',
+} as const;
+export type ConfidenceBracket = typeof ConfidenceBrackets[keyof typeof ConfidenceBrackets];
 
 // ========================================
 // Preset Value Maps

package/src/engines/pricing/index.ts

@@ -72,6 +72,8 @@ export type {
   ProductType,
 
   // Pricing mode types
+  PricingModeName,
+  MetricFormat,
   FlatPricing,
   GraduatedTier,
   GraduatedPricing,
@@ -129,7 +131,7 @@ export type {
 } from './types';
 
 // Currency utilities
-export { CURRENCIES, getCurrencyInfo } from './types';
+export { PricingModeNames, MetricFormats, CURRENCIES, getCurrencyInfo } from './types';
 
 // Compiler
 export { compilePricingRuleSet, compilePricingRule } from './compiler';

package/src/engines/pricing/types.ts

@@ -288,6 +288,15 @@ export type FormulaPricing = {
   calculate: Operand;
 };
 
+export const PricingModeNames = {
+  flat: 'flat',
+  graduated: 'graduated',
+  volume: 'volume',
+  multiMeter: 'multi-meter',
+  formula: 'formula',
+} as const;
+export type PricingModeName = typeof PricingModeNames[keyof typeof PricingModeNames];
+
 /**
  * All pricing modes.
  */
@@ -377,6 +386,13 @@ export type Adjustment = DiscountAdjustment | MinimumAdjustment | MaximumAdjustm
 // Metrics
 // ========================================
 
+export const MetricFormats = {
+  currency: 'currency',
+  percent: 'percent',
+  number: 'number',
+} as const;
+export type MetricFormat = typeof MetricFormats[keyof typeof MetricFormats];
+
 /**
  * Computed metric for comparison.
  */
@@ -388,7 +404,7 @@ export type Metric = {
   /** Expression to compute the metric value */
   calculate: Operand;
   /** Display format */
-  format?: 'currency' | 'percent' | 'number';
+  format?: MetricFormat;
 };
 
 // ========================================

package/src/engines/ranking/index.ts

@@ -30,6 +30,11 @@ export type {
 
 // Constants & utilities
 export {
+  RankingStrategies,
+  RankingDirections,
+  PercentileLabels,
+  Movements,
+  KFactorPresets,
   K_FACTOR_VALUES,
   isKFactorPreset,
   resolvePercentileLabel,

package/src/engines/ranking/types.ts

@@ -18,25 +18,46 @@ import type { SemanticPriority } from '../utility/types';
 // ========================================
 
 /** Ranking algorithm to use */
-export type RankingStrategy = 'score' | 'elo' | 'head-to-head';
+export const RankingStrategies = {
+  score: 'score',
+  elo: 'elo',
+  headToHead: 'head-to-head',
+} as const;
+export type RankingStrategy = typeof RankingStrategies[keyof typeof RankingStrategies];
 
 /** Sort direction for rankings */
-export type RankingDirection = 'highest-first' | 'lowest-first';
+export const RankingDirections = {
+  highestFirst: 'highest-first',
+  lowestFirst: 'lowest-first',
+} as const;
+export type RankingDirection = typeof RankingDirections[keyof typeof RankingDirections];
 
 /** Human-readable percentile bracket */
-export type PercentileLabel =
-  | 'top-1%'
-  | 'top-5%'
-  | 'top-10%'
-  | 'top-25%'
-  | 'top-50%'
-  | 'bottom-half';
+export const PercentileLabels = {
+  top1: 'top-1%',
+  top5: 'top-5%',
+  top10: 'top-10%',
+  top25: 'top-25%',
+  top50: 'top-50%',
+  bottomHalf: 'bottom-half',
+} as const;
+export type PercentileLabel = typeof PercentileLabels[keyof typeof PercentileLabels];
 
 /** Rank movement since previous ranking */
-export type Movement = 'climbed' | 'steady' | 'dropped';
+export const Movements = {
+  climbed: 'climbed',
+  steady: 'steady',
+  dropped: 'dropped',
+} as const;
+export type Movement = typeof Movements[keyof typeof Movements];
 
 /** Elo K-factor presets controlling rating volatility */
-export type KFactorPreset = 'volatile' | 'standard' | 'stable';
+export const KFactorPresets = {
+  volatile: 'volatile',
+  standard: 'standard',
+  stable: 'stable',
+} as const;
+export type KFactorPreset = typeof KFactorPresets[keyof typeof KFactorPresets];
 
 export const K_FACTOR_VALUES: Record<KFactorPreset, number> = {
   'volatile': 32,    // New entities, fast adjustment

package/src/engines/recipe-costing/compiler.ts

@@ -0,0 +1,219 @@
+/**
+ * Recipe Costing Engine Compiler
+ *
+ * Validates recipe costing rulesets and resolves defaults.
+ */
+
+import { CompilationError } from '../../core/errors';
+
+import type {
+  RecipeCostingRuleSet,
+  CompiledRecipeCostingRuleSet,
+  CompiledPlateCostRuleSet,
+  CompiledMarginAnalysisRuleSet,
+  CompiledCostImpactRuleSet
+} from './types';
+
+/**
+ * Compile and validate a recipe costing ruleset.
+ */
+export function compileRecipeCostingRuleSet(
+  ruleSet: RecipeCostingRuleSet
+): CompiledRecipeCostingRuleSet {
+  if (!ruleSet.id) {
+    throw new CompilationError('Recipe costing ruleset requires an id');
+  }
+
+  if (ruleSet.mode !== 'recipe-costing') {
+    throw new CompilationError(`Expected mode 'recipe-costing', got '${ruleSet.mode}'`);
+  }
+
+  if (!ruleSet.ingredients || ruleSet.ingredients.length === 0) {
+    throw new CompilationError('Recipe costing ruleset requires at least one ingredient');
+  }
+
+  if (!ruleSet.recipes || ruleSet.recipes.length === 0) {
+    throw new CompilationError('Recipe costing ruleset requires at least one recipe');
+  }
+
+  // Validate unique ingredient IDs
+  const ingredientIds = new Set<string>();
+  for (const ing of ruleSet.ingredients) {
+    if (!ing.id) {
+      throw new CompilationError('Each ingredient requires an id');
+    }
+    if (ingredientIds.has(ing.id)) {
+      throw new CompilationError(`Duplicate ingredient id: '${ing.id}'`);
+    }
+    if (ing.purchaseQuantity <= 0) {
+      throw new CompilationError(`Ingredient '${ing.id}' purchaseQuantity must be positive`);
+    }
+    if (ing.purchaseCost <= 0) {
+      throw new CompilationError(`Ingredient '${ing.id}' purchaseCost must be positive`);
+    }
+    if (ing.yieldFactor !== undefined && (ing.yieldFactor <= 0 || ing.yieldFactor > 1)) {
+      throw new CompilationError(`Ingredient '${ing.id}' yieldFactor must be in (0, 1]`);
+    }
+    if (ing.wastePct !== undefined && (ing.wastePct < 0 || ing.wastePct >= 100)) {
+      throw new CompilationError(`Ingredient '${ing.id}' wastePct must be in [0, 100)`);
+    }
+    ingredientIds.add(ing.id);
+  }
+
+  // Validate unique recipe IDs
+  const recipeIds = new Set<string>();
+  for (const recipe of ruleSet.recipes) {
+    if (!recipe.id) {
+      throw new CompilationError('Each recipe requires an id');
+    }
+    if (recipeIds.has(recipe.id)) {
+      throw new CompilationError(`Duplicate recipe id: '${recipe.id}'`);
+    }
+    recipeIds.add(recipe.id);
+  }
+
+  // Validate recipe components reference valid ingredients or recipes
+  for (const recipe of ruleSet.recipes) {
+    for (const comp of recipe.components) {
+      if (comp.ingredientId && comp.subRecipeId) {
+        throw new CompilationError(
+          `Recipe '${recipe.id}' component references both ingredientId and subRecipeId. Must be one or the other.`
+        );
+      }
+      if (!comp.ingredientId && !comp.subRecipeId) {
+        throw new CompilationError(
+          `Recipe '${recipe.id}' component must reference an ingredientId or subRecipeId`
+        );
+      }
+      if (comp.ingredientId && !ingredientIds.has(comp.ingredientId)) {
+        throw new CompilationError(
+          `Recipe '${recipe.id}' references unknown ingredient: '${comp.ingredientId}'`
+        );
+      }
+      if (comp.subRecipeId && !recipeIds.has(comp.subRecipeId)) {
+        throw new CompilationError(
+          `Recipe '${recipe.id}' references unknown sub-recipe: '${comp.subRecipeId}'`
+        );
+      }
+    }
+  }
+
+  // Detect circular sub-recipe references
+  detectCircularRecipes(ruleSet.recipes);
+
+  switch (ruleSet.strategy) {
+    case 'plate-cost':
+      return compilePlateCost(ruleSet);
+    case 'margin-analysis':
+      return compileMarginAnalysis(ruleSet);
+    case 'cost-impact':
+      return compileCostImpact(ruleSet);
+    default:
+      throw new CompilationError(`Unknown recipe costing strategy: '${(ruleSet as any).strategy}'`);
+  }
+}
+
+function compilePlateCost(
+  ruleSet: RecipeCostingRuleSet & { strategy: 'plate-cost' }
+): CompiledPlateCostRuleSet {
+  return {
+    id: ruleSet.id,
+    name: ruleSet.name,
+    mode: 'recipe-costing',
+    strategy: 'plate-cost',
+    ingredients: ruleSet.ingredients,
+    recipes: ruleSet.recipes,
+    config: {
+      targetFoodCostPct: ruleSet.config?.targetFoodCostPct ?? 30
+    }
+  };
+}
+
+function compileMarginAnalysis(
+  ruleSet: RecipeCostingRuleSet & { strategy: 'margin-analysis' }
+): CompiledMarginAnalysisRuleSet {
+  return {
+    id: ruleSet.id,
+    name: ruleSet.name,
+    mode: 'recipe-costing',
+    strategy: 'margin-analysis',
+    ingredients: ruleSet.ingredients,
+    recipes: ruleSet.recipes,
+    config: {
+      targetFoodCostPct: ruleSet.config?.targetFoodCostPct ?? 30,
+      flagThreshold: ruleSet.config?.flagThreshold ?? 35
+    }
+  };
+}
+
+function compileCostImpact(
+  ruleSet: RecipeCostingRuleSet & { strategy: 'cost-impact' }
+): CompiledCostImpactRuleSet {
+  if (!ruleSet.config || !ruleSet.config.changes || ruleSet.config.changes.length === 0) {
+    throw new CompilationError('Cost-impact strategy requires at least one cost change');
+  }
+
+  const ingredientIds = new Set(ruleSet.ingredients.map(i => i.id));
+  for (const change of ruleSet.config.changes) {
+    if (!ingredientIds.has(change.ingredientId)) {
+      throw new CompilationError(`Cost change references unknown ingredient: '${change.ingredientId}'`);
+    }
+    if (change.newCost !== undefined && change.percentChange !== undefined) {
+      throw new CompilationError(
+        `Cost change for '${change.ingredientId}' must have newCost or percentChange, not both`
+      );
+    }
+    if (change.newCost === undefined && change.percentChange === undefined) {
+      throw new CompilationError(
+        `Cost change for '${change.ingredientId}' must have newCost or percentChange`
+      );
+    }
+  }
+
+  return {
+    id: ruleSet.id,
+    name: ruleSet.name,
+    mode: 'recipe-costing',
+    strategy: 'cost-impact',
+    ingredients: ruleSet.ingredients,
+    recipes: ruleSet.recipes,
+    config: {
+      changes: ruleSet.config.changes,
+      targetFoodCostPct: ruleSet.config.targetFoodCostPct ?? 30
+    }
+  };
+}
+
+function detectCircularRecipes(recipes: { id: string; components: { subRecipeId?: string }[] }[]): void {
+  const adjacency = new Map<string, string[]>();
+  for (const recipe of recipes) {
+    const deps: string[] = [];
+    for (const comp of recipe.components) {
+      if (comp.subRecipeId) {
+        deps.push(comp.subRecipeId);
+      }
+    }
+    adjacency.set(recipe.id, deps);
+  }
+
+  const visited = new Set<string>();
+  const inStack = new Set<string>();
+
+  function dfs(id: string): void {
+    if (inStack.has(id)) {
+      throw new CompilationError(`Circular sub-recipe dependency detected involving '${id}'`);
+    }
+    if (visited.has(id)) return;
+    visited.add(id);
+    inStack.add(id);
+    const deps = adjacency.get(id) ?? [];
+    for (const dep of deps) {
+      dfs(dep);
+    }
+    inStack.delete(id);
+  }
+
+  for (const recipe of recipes) {
+    dfs(recipe.id);
+  }
+}

package/src/engines/recipe-costing/engine.ts

@@ -0,0 +1,48 @@
+/**
+ * Recipe Costing Engine
+ *
+ * Computes plate cost by rolling up ingredient costs through a bill of
+ * materials with yield factors and waste percentages. Supports margin
+ * analysis and cost-impact modeling when ingredient prices change.
+ *
+ * @example
+ * ```typescript
+ * const engine = new RecipeCostingEngine();
+ *
+ * const result = engine.execute(compiledRecipeCosting);
+ * // result.recipes -> per-recipe cost breakdowns
+ * ```
+ */
+
+import type {
+  CompiledRecipeCostingRuleSet,
+  RecipeCostingOptions,
+  RecipeCostingResult
+} from './types';
+
+import { RecipeCostingExecutor } from './strategy';
+
+export class RecipeCostingEngine {
+  private strategy: RecipeCostingExecutor;
+
+  constructor() {
+    this.strategy = new RecipeCostingExecutor();
+  }
+
+  /**
+   * Execute a recipe costing ruleset.
+   *
+   * Computes plate costs, analyzes margins, or models cost impacts
+   * depending on the strategy.
+   *
+   * @param ruleSet - Compiled recipe costing ruleset
+   * @param options - Runtime options
+   * @returns Recipe costing result
+   */
+  execute(
+    ruleSet: CompiledRecipeCostingRuleSet,
+    options: RecipeCostingOptions = {}
+  ): RecipeCostingResult {
+    return this.strategy.run(ruleSet, options);
+  }
+}

package/src/engines/recipe-costing/index.ts

@@ -0,0 +1,48 @@
+/**
+ * Recipe Costing Engine -- Plate Cost & Margin Analysis
+ */
+
+// Types
+export type {
+  RecipeCostingStrategy,
+  MeasurementUnit,
+  Ingredient,
+  RecipeComponent,
+  Recipe,
+  CostChange,
+  PlateCostConfig,
+  MarginAnalysisConfig,
+  CostImpactConfig,
+  PlateCostRuleSet,
+  MarginAnalysisRuleSet,
+  CostImpactRuleSet,
+  RecipeCostingRuleSet,
+  CompiledPlateCostRuleSet,
+  CompiledMarginAnalysisRuleSet,
+  CompiledCostImpactRuleSet,
+  CompiledRecipeCostingRuleSet,
+  IngredientCostBreakdown,
+  SubRecipeCostBreakdown,
+  RecipeCostResult,
+  CostImpactItem,
+  PlateCostResult,
+  MarginAnalysisResult,
+  CostImpactResult,
+  RecipeCostingResult,
+  RecipeCostingOptions
+} from './types';
+
+// Constants
+export {
+  RecipeCostingStrategies,
+  MeasurementUnits
+} from './types';
+
+// Compiler
+export { compileRecipeCostingRuleSet } from './compiler';
+
+// Strategy
+export { RecipeCostingExecutor, recipeCostingStrategy } from './strategy';
+
+// Engine
+export { RecipeCostingEngine } from './engine';