@higher.archi/boe 1.0.30 → 1.0.31

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

@@ -0,0 +1,357 @@
+/**
+ * Recipe Costing Engine Strategy
+ *
+ * Core execution logic for all recipe costing strategies:
+ * - plate-cost: compute plate cost by rolling up ingredient BOM with yield/waste
+ * - margin-analysis: analyze margins and flag high food-cost items
+ * - cost-impact: model ingredient cost changes and their impact on recipes
+ */
+
+import type {
+  CompiledRecipeCostingRuleSet,
+  CompiledPlateCostRuleSet,
+  CompiledMarginAnalysisRuleSet,
+  CompiledCostImpactRuleSet,
+  Ingredient,
+  Recipe,
+  RecipeCostResult,
+  IngredientCostBreakdown,
+  SubRecipeCostBreakdown,
+  CostImpactItem,
+  PlateCostResult,
+  MarginAnalysisResult,
+  CostImpactResult,
+  RecipeCostingResult,
+  RecipeCostingOptions
+} from './types';
+
+// ========================================
+// Helpers
+// ========================================
+
+function round(value: number, decimals: number): number {
+  const factor = Math.pow(10, decimals);
+  return Math.round(value * factor) / factor;
+}
+
+function computeIngredientCostPerUnit(ing: Ingredient): number {
+  const baseCostPerUnit = ing.purchaseCost / ing.purchaseQuantity;
+  const yieldFactor = ing.yieldFactor ?? 1;
+  const wastePct = ing.wastePct ?? 0;
+  return baseCostPerUnit / yieldFactor / (1 - wastePct / 100);
+}
+
+// ========================================
+// Strategy Executor
+// ========================================
+
+export class RecipeCostingExecutor {
+  run(
+    ruleSet: CompiledRecipeCostingRuleSet,
+    _options: RecipeCostingOptions = {}
+  ): RecipeCostingResult {
+    switch (ruleSet.strategy) {
+      case 'plate-cost':
+        return this.runPlateCost(ruleSet);
+      case 'margin-analysis':
+        return this.runMarginAnalysis(ruleSet);
+      case 'cost-impact':
+        return this.runCostImpact(ruleSet);
+      default:
+        throw new Error(`Unknown recipe costing strategy: '${(ruleSet as any).strategy}'`);
+    }
+  }
+
+  // ========================================
+  // Plate Cost Strategy
+  // ========================================
+
+  private runPlateCost(ruleSet: CompiledPlateCostRuleSet): PlateCostResult {
+    const startTime = performance.now();
+
+    const ingredientMap = new Map(ruleSet.ingredients.map(i => [i.id, i]));
+    const recipeMap = new Map(ruleSet.recipes.map(r => [r.id, r]));
+    const targetFoodCostPct = ruleSet.config.targetFoodCostPct;
+
+    const recipes = ruleSet.recipes.map(recipe =>
+      this.computeRecipeCost(recipe, ingredientMap, recipeMap, targetFoodCostPct, new Set())
+    );
+
+    const executionTimeMs = round((performance.now() - startTime) * 100, 0) / 100;
+
+    return { recipes, executionTimeMs };
+  }
+
+  // ========================================
+  // Margin Analysis Strategy
+  // ========================================
+
+  private runMarginAnalysis(ruleSet: CompiledMarginAnalysisRuleSet): MarginAnalysisResult {
+    const startTime = performance.now();
+
+    const ingredientMap = new Map(ruleSet.ingredients.map(i => [i.id, i]));
+    const recipeMap = new Map(ruleSet.recipes.map(r => [r.id, r]));
+    const { targetFoodCostPct, flagThreshold } = ruleSet.config;
+
+    const allRecipes = ruleSet.recipes.map(recipe =>
+      this.computeRecipeCost(recipe, ingredientMap, recipeMap, targetFoodCostPct, new Set())
+    );
+
+    // Filter to recipes with selling price and sort by contribution margin descending
+    const recipesWithPrice = allRecipes
+      .filter(r => r.sellingPrice !== undefined)
+      .sort((a, b) => (b.contributionMargin ?? 0) - (a.contributionMargin ?? 0));
+
+    // Flag items above threshold
+    const flaggedItems = recipesWithPrice.filter(
+      r => r.foodCostPct !== undefined && r.foodCostPct > flagThreshold
+    );
+
+    // Compute summary stats
+    const validRecipes = recipesWithPrice.filter(r => r.foodCostPct !== undefined);
+    const avgFoodCostPct = validRecipes.length > 0
+      ? round(validRecipes.reduce((sum, r) => sum + r.foodCostPct!, 0) / validRecipes.length, 2)
+      : 0;
+    const avgContributionMargin = validRecipes.length > 0
+      ? round(validRecipes.reduce((sum, r) => sum + r.contributionMargin!, 0) / validRecipes.length, 2)
+      : 0;
+
+    const executionTimeMs = round((performance.now() - startTime) * 100, 0) / 100;
+
+    return {
+      recipes: allRecipes,
+      flaggedItems,
+      summary: {
+        totalRecipes: allRecipes.length,
+        recipesWithPrice: recipesWithPrice.length,
+        avgFoodCostPct,
+        avgContributionMargin,
+        flaggedCount: flaggedItems.length
+      },
+      executionTimeMs
+    };
+  }
+
+  // ========================================
+  // Cost Impact Strategy
+  // ========================================
+
+  private runCostImpact(ruleSet: CompiledCostImpactRuleSet): CostImpactResult {
+    const startTime = performance.now();
+
+    const ingredientMap = new Map(ruleSet.ingredients.map(i => [i.id, i]));
+    const recipeMap = new Map(ruleSet.recipes.map(r => [r.id, r]));
+    const { changes, targetFoodCostPct } = ruleSet.config;
+
+    // Compute baseline costs
+    const baselineCosts = new Map<string, RecipeCostResult>();
+    for (const recipe of ruleSet.recipes) {
+      baselineCosts.set(
+        recipe.id,
+        this.computeRecipeCost(recipe, ingredientMap, recipeMap, targetFoodCostPct, new Set())
+      );
+    }
+
+    // Clone and modify ingredient map
+    const modifiedIngredientMap = new Map(
+      ruleSet.ingredients.map(i => [i.id, { ...i }])
+    );
+    const changedIngredientIds = new Set<string>();
+    for (const change of changes) {
+      const ing = modifiedIngredientMap.get(change.ingredientId)!;
+      if (change.newCost !== undefined) {
+        ing.purchaseCost = change.newCost;
+      } else if (change.percentChange !== undefined) {
+        ing.purchaseCost = ing.purchaseCost * (1 + change.percentChange / 100);
+      }
+      changedIngredientIds.add(change.ingredientId);
+    }
+
+    // Recompute costs with modified ingredients
+    const impactItems: CostImpactItem[] = [];
+    for (const recipe of ruleSet.recipes) {
+      const newResult = this.computeRecipeCost(
+        recipe, modifiedIngredientMap, recipeMap, targetFoodCostPct, new Set()
+      );
+      const baseline = baselineCosts.get(recipe.id)!;
+
+      // Check if this recipe is affected
+      const affectedIngredients = this.findAffectedIngredients(
+        recipe, recipeMap, changedIngredientIds
+      );
+
+      if (affectedIngredients.length === 0) continue;
+
+      const plateCostChange = round(newResult.plateCost - baseline.plateCost, 4);
+      const plateCostChangePct = baseline.plateCost > 0
+        ? round((plateCostChange / baseline.plateCost) * 100, 2)
+        : 0;
+
+      impactItems.push({
+        recipeId: recipe.id,
+        recipeName: recipe.name,
+        oldPlateCost: baseline.plateCost,
+        newPlateCost: newResult.plateCost,
+        plateCostChange,
+        plateCostChangePct,
+        oldFoodCostPct: baseline.foodCostPct,
+        newFoodCostPct: newResult.foodCostPct,
+        oldMargin: baseline.contributionMargin,
+        newMargin: newResult.contributionMargin,
+        affectedIngredients
+      });
+    }
+
+    // Sort by impact severity (largest absolute change first)
+    impactItems.sort((a, b) => Math.abs(b.plateCostChange) - Math.abs(a.plateCostChange));
+
+    // Compute summary
+    const avgPlateCostChange = impactItems.length > 0
+      ? round(impactItems.reduce((sum, i) => sum + i.plateCostChange, 0) / impactItems.length, 4)
+      : 0;
+    const avgPlateCostChangePct = impactItems.length > 0
+      ? round(impactItems.reduce((sum, i) => sum + i.plateCostChangePct, 0) / impactItems.length, 2)
+      : 0;
+    const itemsCrossingThreshold = impactItems.filter(i =>
+      i.oldFoodCostPct !== undefined &&
+      i.newFoodCostPct !== undefined &&
+      i.oldFoodCostPct <= targetFoodCostPct &&
+      i.newFoodCostPct > targetFoodCostPct
+    ).length;
+
+    const executionTimeMs = round((performance.now() - startTime) * 100, 0) / 100;
+
+    return {
+      items: impactItems,
+      summary: {
+        totalRecipesAffected: impactItems.length,
+        avgPlateCostChange,
+        avgPlateCostChangePct,
+        itemsCrossingThreshold
+      },
+      executionTimeMs
+    };
+  }
+
+  // ========================================
+  // Shared Helpers
+  // ========================================
+
+  private computeRecipeCost(
+    recipe: Recipe,
+    ingredientMap: Map<string, Ingredient>,
+    recipeMap: Map<string, Recipe>,
+    targetFoodCostPct: number,
+    visited: Set<string>
+  ): RecipeCostResult {
+    if (visited.has(recipe.id)) {
+      throw new Error(`Circular sub-recipe dependency detected at '${recipe.id}'`);
+    }
+    visited.add(recipe.id);
+
+    const batchSize = recipe.batchSize ?? 1;
+    const ingredients: IngredientCostBreakdown[] = [];
+    const subRecipes: SubRecipeCostBreakdown[] = [];
+    let totalBatchCost = 0;
+
+    for (const comp of recipe.components) {
+      if (comp.ingredientId) {
+        const ing = ingredientMap.get(comp.ingredientId)!;
+        const costPerUnit = computeIngredientCostPerUnit(ing);
+        const lineCost = round(costPerUnit * comp.quantity, 4);
+        totalBatchCost += lineCost;
+
+        ingredients.push({
+          ingredientId: ing.id,
+          ingredientName: ing.name,
+          quantity: comp.quantity,
+          unit: comp.unit,
+          costPerUnit: round(costPerUnit, 4),
+          lineCost,
+          pctOfPlateCost: 0 // filled in below
+        });
+      } else if (comp.subRecipeId) {
+        const subRecipe = recipeMap.get(comp.subRecipeId)!;
+        const subResult = this.computeRecipeCost(
+          subRecipe, ingredientMap, recipeMap, targetFoodCostPct, new Set(visited)
+        );
+        const costPerPortion = subResult.plateCost;
+        const lineCost = round(costPerPortion * comp.quantity, 4);
+        totalBatchCost += lineCost;
+
+        subRecipes.push({
+          subRecipeId: subRecipe.id,
+          subRecipeName: subRecipe.name,
+          quantity: comp.quantity,
+          costPerPortion: round(costPerPortion, 4),
+          lineCost,
+          pctOfPlateCost: 0 // filled in below
+        });
+      }
+    }
+
+    const plateCost = round(totalBatchCost / batchSize, 4);
+
+    // Fill in pctOfPlateCost
+    if (totalBatchCost > 0) {
+      for (const ing of ingredients) {
+        ing.pctOfPlateCost = round((ing.lineCost / totalBatchCost) * 100, 2);
+      }
+      for (const sub of subRecipes) {
+        sub.pctOfPlateCost = round((sub.lineCost / totalBatchCost) * 100, 2);
+      }
+    }
+
+    const result: RecipeCostResult = {
+      recipeId: recipe.id,
+      recipeName: recipe.name,
+      category: recipe.category,
+      batchSize,
+      totalBatchCost: round(totalBatchCost, 4),
+      plateCost,
+      ingredients,
+      subRecipes
+    };
+
+    if (recipe.sellingPrice !== undefined) {
+      result.sellingPrice = recipe.sellingPrice;
+      result.contributionMargin = round(recipe.sellingPrice - plateCost, 4);
+      result.foodCostPct = recipe.sellingPrice > 0
+        ? round((plateCost / recipe.sellingPrice) * 100, 2)
+        : 0;
+      result.meetsTarget = result.foodCostPct <= targetFoodCostPct;
+    }
+
+    visited.delete(recipe.id);
+    return result;
+  }
+
+  private findAffectedIngredients(
+    recipe: Recipe,
+    recipeMap: Map<string, Recipe>,
+    changedIds: Set<string>,
+    visited: Set<string> = new Set()
+  ): string[] {
+    if (visited.has(recipe.id)) return [];
+    visited.add(recipe.id);
+
+    const affected: string[] = [];
+    for (const comp of recipe.components) {
+      if (comp.ingredientId && changedIds.has(comp.ingredientId)) {
+        affected.push(comp.ingredientId);
+      }
+      if (comp.subRecipeId) {
+        const subRecipe = recipeMap.get(comp.subRecipeId);
+        if (subRecipe) {
+          affected.push(
+            ...this.findAffectedIngredients(subRecipe, recipeMap, changedIds, visited)
+          );
+        }
+      }
+    }
+    return [...new Set(affected)];
+  }
+}
+
+/** Singleton instance */
+export const recipeCostingStrategy = new RecipeCostingExecutor();

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

@@ -0,0 +1,269 @@
+/**
+ * Recipe Costing Engine Types
+ *
+ * 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.
+ */
+
+// ========================================
+// Semantic Types
+// ========================================
+
+/** Recipe costing strategy to use */
+export const RecipeCostingStrategies = {
+  plateCost: 'plate-cost',
+  marginAnalysis: 'margin-analysis',
+  costImpact: 'cost-impact',
+} as const;
+export type RecipeCostingStrategy = typeof RecipeCostingStrategies[keyof typeof RecipeCostingStrategies];
+
+/** Measurement unit for ingredients and recipes */
+export const MeasurementUnits = {
+  oz: 'oz',
+  lb: 'lb',
+  g: 'g',
+  kg: 'kg',
+  flOz: 'fl_oz',
+  cup: 'cup',
+  qt: 'qt',
+  gal: 'gal',
+  ml: 'ml',
+  l: 'l',
+  each: 'each',
+  slice: 'slice',
+  portion: 'portion',
+} as const;
+export type MeasurementUnit = typeof MeasurementUnits[keyof typeof MeasurementUnits];
+
+// ========================================
+// Core Domain Types
+// ========================================
+
+/** An ingredient with purchase cost and yield data */
+export type Ingredient = {
+  id: string;
+  name: string;
+  category?: string;
+  purchaseUnit: MeasurementUnit;
+  purchaseQuantity: number;
+  purchaseCost: number;
+  yieldFactor?: number;
+  wastePct?: number;
+  unit: MeasurementUnit;
+};
+
+/** A component in a recipe (ingredient or sub-recipe) */
+export type RecipeComponent = {
+  ingredientId?: string;
+  subRecipeId?: string;
+  quantity: number;
+  unit: MeasurementUnit;
+};
+
+/** A recipe with components and optional selling price */
+export type Recipe = {
+  id: string;
+  name: string;
+  category?: string;
+  sellingPrice?: number;
+  components: RecipeComponent[];
+  batchSize?: number;
+};
+
+/** A cost change for an ingredient */
+export type CostChange = {
+  ingredientId: string;
+  newCost?: number;
+  percentChange?: number;
+};
+
+// ========================================
+// Config Types
+// ========================================
+
+/** Configuration for plate-cost strategy */
+export type PlateCostConfig = {
+  targetFoodCostPct?: number;
+};
+
+/** Configuration for margin-analysis strategy */
+export type MarginAnalysisConfig = {
+  targetFoodCostPct?: number;
+  flagThreshold?: number;
+};
+
+/** Configuration for cost-impact strategy */
+export type CostImpactConfig = {
+  changes: CostChange[];
+  targetFoodCostPct?: number;
+};
+
+// ========================================
+// Source RuleSet Types (Discriminated Union)
+// ========================================
+
+type RecipeCostingRuleSetBase = {
+  id: string;
+  name?: string;
+  mode: 'recipe-costing';
+  ingredients: Ingredient[];
+  recipes: Recipe[];
+};
+
+/** Plate-cost strategy: compute cost per portion for each recipe */
+export type PlateCostRuleSet = RecipeCostingRuleSetBase & {
+  strategy: 'plate-cost';
+  config?: PlateCostConfig;
+};
+
+/** Margin-analysis strategy: analyze margins and flag high food-cost items */
+export type MarginAnalysisRuleSet = RecipeCostingRuleSetBase & {
+  strategy: 'margin-analysis';
+  config?: MarginAnalysisConfig;
+};
+
+/** Cost-impact strategy: model ingredient cost changes */
+export type CostImpactRuleSet = RecipeCostingRuleSetBase & {
+  strategy: 'cost-impact';
+  config: CostImpactConfig;
+};
+
+export type RecipeCostingRuleSet =
+  | PlateCostRuleSet
+  | MarginAnalysisRuleSet
+  | CostImpactRuleSet;
+
+// ========================================
+// Compiled RuleSet Types
+// ========================================
+
+type CompiledRecipeCostingRuleSetBase = {
+  id: string;
+  name?: string;
+  mode: 'recipe-costing';
+  ingredients: Ingredient[];
+  recipes: Recipe[];
+};
+
+export type CompiledPlateCostRuleSet = CompiledRecipeCostingRuleSetBase & {
+  strategy: 'plate-cost';
+  config: {
+    targetFoodCostPct: number;
+  };
+};
+
+export type CompiledMarginAnalysisRuleSet = CompiledRecipeCostingRuleSetBase & {
+  strategy: 'margin-analysis';
+  config: {
+    targetFoodCostPct: number;
+    flagThreshold: number;
+  };
+};
+
+export type CompiledCostImpactRuleSet = CompiledRecipeCostingRuleSetBase & {
+  strategy: 'cost-impact';
+  config: {
+    changes: CostChange[];
+    targetFoodCostPct: number;
+  };
+};
+
+export type CompiledRecipeCostingRuleSet =
+  | CompiledPlateCostRuleSet
+  | CompiledMarginAnalysisRuleSet
+  | CompiledCostImpactRuleSet;
+
+// ========================================
+// Result Types
+// ========================================
+
+/** Cost breakdown for a single ingredient in a recipe */
+export type IngredientCostBreakdown = {
+  ingredientId: string;
+  ingredientName: string;
+  quantity: number;
+  unit: MeasurementUnit;
+  costPerUnit: number;
+  lineCost: number;
+  pctOfPlateCost: number;
+};
+
+/** Cost breakdown for a sub-recipe in a recipe */
+export type SubRecipeCostBreakdown = {
+  subRecipeId: string;
+  subRecipeName: string;
+  quantity: number;
+  costPerPortion: number;
+  lineCost: number;
+  pctOfPlateCost: number;
+};
+
+/** Cost result for a single recipe */
+export type RecipeCostResult = {
+  recipeId: string;
+  recipeName: string;
+  category?: string;
+  batchSize: number;
+  totalBatchCost: number;
+  plateCost: number;
+  sellingPrice?: number;
+  contributionMargin?: number;
+  foodCostPct?: number;
+  meetsTarget?: boolean;
+  ingredients: IngredientCostBreakdown[];
+  subRecipes: SubRecipeCostBreakdown[];
+};
+
+/** Cost impact for a single recipe when ingredients change */
+export type CostImpactItem = {
+  recipeId: string;
+  recipeName: string;
+  oldPlateCost: number;
+  newPlateCost: number;
+  plateCostChange: number;
+  plateCostChangePct: number;
+  oldFoodCostPct?: number;
+  newFoodCostPct?: number;
+  oldMargin?: number;
+  newMargin?: number;
+  affectedIngredients: string[];
+};
+
+/** Result from plate-cost strategy */
+export type PlateCostResult = {
+  recipes: RecipeCostResult[];
+  executionTimeMs: number;
+};
+
+/** Result from margin-analysis strategy */
+export type MarginAnalysisResult = {
+  recipes: RecipeCostResult[];
+  flaggedItems: RecipeCostResult[];
+  summary: {
+    totalRecipes: number;
+    recipesWithPrice: number;
+    avgFoodCostPct: number;
+    avgContributionMargin: number;
+    flaggedCount: number;
+  };
+  executionTimeMs: number;
+};
+
+/** Result from cost-impact strategy */
+export type CostImpactResult = {
+  items: CostImpactItem[];
+  summary: {
+    totalRecipesAffected: number;
+    avgPlateCostChange: number;
+    avgPlateCostChangePct: number;
+    itemsCrossingThreshold: number;
+  };
+  executionTimeMs: number;
+};
+
+/** Union of all recipe costing results */
+export type RecipeCostingResult = PlateCostResult | MarginAnalysisResult | CostImpactResult;
+
+/** Runtime options */
+export type RecipeCostingOptions = Record<string, never>;

package/src/engines/scoring/index.ts

@@ -7,6 +7,8 @@
 
 // Types
 export {
+  // Scoring method const
+  ScoringMethods,
   // Scoring methods
   ScoringMethod,
   ScoringCaps,

package/src/engines/scoring/types.ts

@@ -26,12 +26,14 @@ import { DecayConfig, DecayInfo } from '../../core/evaluation/decay';
  * - Per-rule methods (normalized, capped, adaptive): Applied to each rule's score
  * - Global methods (weighted-percent): Applied across all rules
  */
-export type ScoringMethod =
-  | 'raw'              // No normalization (pass-through)
-  | 'normalized'       // Normalize scores to 0-1 range using min/max bounds (strict - requires normalize field)
-  | 'adaptive'         // Smart normalization: use provided bounds or auto-detect from observed max
-  | 'weighted-percent' // Auto-normalize weights to sum to 1.0
-  | 'capped';          // Apply max caps to rule contributions
+export const ScoringMethods = {
+  raw: 'raw',
+  normalized: 'normalized',
+  adaptive: 'adaptive',
+  weightedPercent: 'weighted-percent',
+  capped: 'capped',
+} as const;
+export type ScoringMethod = typeof ScoringMethods[keyof typeof ScoringMethods];
 
 /**
  * Max contribution caps for each rule

package/src/engines/sentiment/index.ts

@@ -28,6 +28,8 @@ export type {
 
 // Constants & utilities
 export {
+  SentimentStrategies,
+  SentimentLabels,
   SENTIMENT_DEFAULTS,
   resolveSentimentLabel
 } from './types';

package/src/engines/sentiment/types.ts

@@ -11,10 +11,21 @@
 // ========================================
 
 /** Sentiment analysis strategy */
-export type SentimentStrategy = 'token-level' | 'document-level' | 'aspect-based';
+export const SentimentStrategies = {
+  tokenLevel: 'token-level',
+  documentLevel: 'document-level',
+  aspectBased: 'aspect-based',
+} as const;
+export type SentimentStrategy = typeof SentimentStrategies[keyof typeof SentimentStrategies];
 
 /** Resolved sentiment label */
-export type SentimentLabel = 'positive' | 'neutral' | 'negative' | 'mixed';
+export const SentimentLabels = {
+  positive: 'positive',
+  neutral: 'neutral',
+  negative: 'negative',
+  mixed: 'mixed',
+} as const;
+export type SentimentLabel = typeof SentimentLabels[keyof typeof SentimentLabels];
 
 // ========================================
 // Lexicon Types

package/src/engines/state-machine/index.ts

@@ -7,6 +7,9 @@
 
 // Types
 export {
+  // Constants
+  ActionTypes,
+  ActionType,
   // Source types
   StateMachineDefinition,
   StateMachineConfig,