@higher.archi/boe 1.0.0

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

@@ -0,0 +1,254 @@
+/**
+ * State Machine Engine Types
+ *
+ * Defines types for state machine definitions, transitions, guards, and actions.
+ * State machines track entity lifecycle through defined states and transitions.
+ */
+
+import {
+  Condition
+} from '../../core';
+
+// ========================================
+// Source Types (User-Defined)
+// ========================================
+
+/**
+ * Action to execute on state entry, exit, or during transition.
+ * Uses the same familiar syntax as forward chaining actions.
+ */
+export type StateMachineActionItem =
+  | { set: Record<string, any> }           // Set context properties: { set: { paidAt: '$now' } }
+  | { emit: string; data?: Record<string, any> }  // Emit event: { emit: 'OrderPaid', data: { orderId: '$context.orderId' } }
+  | { call: string }                       // Call handler: { call: 'notifyWarehouse' }
+  | { log: string };                       // Log message: { log: 'Order $context.orderId paid' }
+
+/**
+ * A transition between states
+ */
+export type StateTransition = {
+  /** Event that triggers this transition */
+  event: string;
+  /** Target state to transition to */
+  target: string;
+  /** Optional guard condition - transition only if true */
+  guard?: Condition;
+  /** Actions to execute during transition */
+  actions?: StateMachineActionItem[];
+};
+
+/**
+ * A state definition
+ */
+export type StateDefinition = {
+  /** Mark as final (terminal) state - no transitions out */
+  type?: 'final' | 'parallel';
+  /** Initial sub-state for compound states */
+  initial?: string;
+  /** Nested states for hierarchical state machines */
+  states?: Record<string, StateDefinition>;
+  /** Transitions from this state */
+  transitions?: StateTransition[];
+  /** Actions to execute when entering this state */
+  onEnter?: StateMachineActionItem[];
+  /** Actions to execute when exiting this state */
+  onExit?: StateMachineActionItem[];
+};
+
+/**
+ * State machine definition (source format)
+ */
+export type StateMachineDefinition = {
+  /** Unique identifier */
+  id: string;
+  /** Human-readable name */
+  name?: string;
+  /** Engine mode */
+  mode: 'state-machine';
+  /** Initial state */
+  initial: string;
+  /** Initial context data */
+  context?: Record<string, any>;
+  /** State definitions */
+  states: Record<string, StateDefinition>;
+  /** Configuration options */
+  config?: Partial<StateMachineConfig>;
+};
+
+/**
+ * State machine configuration
+ */
+export type StateMachineConfig = {
+  mode: 'state-machine';
+  /** Whether to throw on invalid transitions (default: true) */
+  strict: boolean;
+  /** Maximum transition history to keep (default: 100) */
+  maxHistory: number;
+};
+
+// ========================================
+// Compiled Types
+// ========================================
+
+/**
+ * Compiled action item (normalized internal format)
+ */
+export type CompiledStateMachineAction = {
+  type: 'set' | 'emit' | 'call' | 'log';
+  /** For 'set': map of path arrays to values */
+  assignments?: Array<{ path: string[]; value: any }>;
+  /** For 'emit': event name */
+  event?: string;
+  /** For 'emit': event data */
+  data?: Record<string, any>;
+  /** For 'call': handler name */
+  handler?: string;
+  /** For 'log': message template */
+  message?: string;
+};
+
+/**
+ * Compiled transition
+ */
+export type CompiledTransition = {
+  event: string;
+  target: string;
+  guard?: any; // Compiled condition
+  actions: CompiledStateMachineAction[];
+};
+
+/**
+ * Compiled state definition
+ */
+export type CompiledStateDefinition = {
+  name: string;
+  type?: 'final' | 'parallel';
+  initial?: string;
+  states?: Record<string, CompiledStateDefinition>;
+  transitions: CompiledTransition[];
+  onEnter: CompiledStateMachineAction[];
+  onExit: CompiledStateMachineAction[];
+  /** All valid events from this state */
+  validEvents: string[];
+  /** Parent state name (for hierarchical) */
+  parent?: string;
+};
+
+/**
+ * Compiled state machine definition
+ */
+export type CompiledStateMachineDefinition = {
+  id: string;
+  name?: string;
+  mode: 'state-machine';
+  initial: string;
+  initialContext: Record<string, any>;
+  states: Record<string, CompiledStateDefinition>;
+  /** Flattened map of all states including nested */
+  stateMap: Map<string, CompiledStateDefinition>;
+  config: StateMachineConfig;
+};
+
+// ========================================
+// Runtime Types
+// ========================================
+
+/**
+ * A snapshot of machine state (serializable)
+ */
+export type MachineSnapshot = {
+  /** Current state (dot-notation for nested: "active.running") */
+  state: string;
+  /** Current context data */
+  context: Record<string, any>;
+  /** Transition history */
+  history: TransitionRecord[];
+};
+
+/**
+ * Record of a transition that occurred
+ */
+export type TransitionRecord = {
+  from: string;
+  to: string;
+  event: string;
+  timestamp: string;
+  payload?: any;
+};
+
+/**
+ * Handler for custom actions
+ */
+export type StateMachineActionHandler = (
+  context: Record<string, any>,
+  event: { type: string; payload?: any },
+  meta: { from: string; to: string }
+) => void;
+
+/**
+ * Registry of action handlers
+ */
+export type StateMachineActionRegistry = Record<string, StateMachineActionHandler>;
+
+/**
+ * Event listener for state machine events
+ */
+export type StateMachineEventListener = (
+  event: string,
+  data: Record<string, any>,
+  snapshot: MachineSnapshot
+) => void;
+
+/**
+ * Options for state machine execution
+ */
+export type StateMachineOptions = {
+  /** Custom action handlers */
+  actions?: StateMachineActionRegistry;
+  /** Event listener for emitted events */
+  onEmit?: StateMachineEventListener;
+  /** Callback when state changes */
+  onTransition?: (from: string, to: string, event: string) => void;
+  /** Temporal override for testing */
+  temporal?: Date;
+};
+
+/**
+ * Result of a transition attempt
+ */
+export type TransitionResult = {
+  /** Whether transition succeeded */
+  success: boolean;
+  /** Previous state */
+  from: string;
+  /** New state (same as 'from' if failed) */
+  to: string;
+  /** Event that triggered transition */
+  event: string;
+  /** Error message if failed */
+  error?: string;
+  /** Actions that were executed */
+  actionsExecuted: string[];
+};
+
+/**
+ * A live state machine instance
+ */
+export interface IStateMachineInstance {
+  /** Current state */
+  readonly state: string;
+  /** Current context */
+  readonly context: Record<string, any>;
+  /** Check if event is valid from current state */
+  can(event: string): boolean;
+  /** Get all valid events from current state */
+  nextEvents(): string[];
+  /** Send an event to trigger transition */
+  send(event: string, payload?: any): TransitionResult;
+  /** Check if machine is in a final state */
+  isFinal(): boolean;
+  /** Get serializable snapshot */
+  snapshot(): MachineSnapshot;
+  /** Get transition history */
+  history(): TransitionRecord[];
+}

package/src/engines/utility/compiler.ts

@@ -0,0 +1,208 @@
+/**
+ * Utility/MCDM Engine Compiler
+ */
+
+import {
+  compileCondition,
+  normalizeShape,
+  Condition
+} from '../../core';
+
+import {
+  UtilityRule,
+  UtilityRuleSet,
+  UtilityConfig,
+  UtilityCriterion,
+  CompiledUtilityRule,
+  CompiledUtilityRuleSet,
+  CompiledUtilityCriterion,
+  isSemanticPriority,
+  SEMANTIC_PRIORITY_VALUES
+} from './types';
+
+// ========================================
+// Helper Functions
+// ========================================
+
+function countConditions(condition?: any): number {
+  if (!condition) return 0;
+  if (condition.children) {
+    return 1 + condition.children.reduce((sum: number, c: any) => sum + countConditions(c), 0);
+  }
+  return 1;
+}
+
+function calculateComplexity(inputs: any[], where?: any): number {
+  let score = 0;
+  score += inputs.length * 10;
+  score += countConditions(where) * 5;
+  for (const input of inputs) {
+    score += countConditions(input.where) * 2;
+  }
+  return score;
+}
+
+function compilePath(from: string) {
+  const str = from.startsWith('$') ? from.slice(1) : from;
+  const parts = str.split('.');
+  return {
+    param: parts[0],
+    path: parts.slice(1)
+  };
+}
+
+// ========================================
+// Parameter Compilation
+// ========================================
+
+function compileInputParameter(input: any) {
+  const compiled: any = {
+    name: input.name,
+    type: input.type,
+    schema: input.shape ? normalizeShape(input.shape) : { type: 'object' }
+  };
+
+  if (input.where) {
+    compiled.where = compileCondition(input.where);
+  }
+
+  if (input.from) {
+    compiled.from = compilePath(input.from);
+  }
+
+  return compiled;
+}
+
+// ========================================
+// Criterion Compilation
+// ========================================
+
+/**
+ * Convert a criterion weight to a numeric value.
+ * Handles both numeric weights (0-1) and semantic priorities.
+ */
+function resolveWeight(weight: number | string): number {
+  if (typeof weight === 'number') {
+    return weight;
+  }
+  if (isSemanticPriority(weight)) {
+    return SEMANTIC_PRIORITY_VALUES[weight];
+  }
+  throw new Error(`Invalid weight value: ${weight}. Must be a number (0-1) or SemanticPriority`);
+}
+
+/**
+ * Compile a single criterion, converting semantic weights to numeric values.
+ * Note: Weights are normalized later in compileUtilityRuleSet.
+ */
+function compileCriterion(criterion: UtilityCriterion): CompiledUtilityCriterion {
+  const numericWeight = resolveWeight(criterion.weight);
+
+  // For numeric weights, validate 0-1 range (semantic weights use different scale)
+  if (typeof criterion.weight === 'number' && (numericWeight < 0 || numericWeight > 1)) {
+    throw new Error(`Numeric criterion weight must be between 0 and 1, got ${numericWeight} for "${criterion.id}"`);
+  }
+
+  return {
+    id: criterion.id,
+    name: criterion.name,
+    weight: numericWeight,
+    direction: criterion.direction
+  };
+}
+
+/**
+ * Normalize criterion weights so they sum to 1.0.
+ * This allows semantic weights (which use a different scale) to work correctly.
+ */
+function normalizeWeights(criteria: CompiledUtilityCriterion[]): void {
+  const totalWeight = criteria.reduce((sum, c) => sum + c.weight, 0);
+
+  if (totalWeight === 0) {
+    throw new Error('At least one criterion must have a non-zero weight');
+  }
+
+  for (const criterion of criteria) {
+    criterion.weight = criterion.weight / totalWeight;
+  }
+}
+
+// ========================================
+// Rule Compilation
+// ========================================
+
+export function compileUtilityRule(rule: UtilityRule, index: number = 0): CompiledUtilityRule {
+  const inputs = rule.inputs.map(compileInputParameter);
+  const when = rule.when ? compileCondition(rule.when) : undefined;
+
+  // Compile the compute expression
+  const compute = compileCondition(rule.compute as Condition);
+
+  return {
+    id: rule.id,
+    name: rule.name,
+    salience: rule.salience ?? 0,
+    complexity: calculateComplexity(inputs, when),
+    index,
+    inputs,
+    when,
+    criterion: rule.criterion,
+    compute
+  };
+}
+
+// ========================================
+// RuleSet Compilation
+// ========================================
+
+export function compileUtilityRuleSet(ruleSet: UtilityRuleSet): CompiledUtilityRuleSet {
+  // Validate criteria
+  if (!ruleSet.criteria || ruleSet.criteria.length === 0) {
+    throw new Error('UtilityRuleSet must have at least one criterion');
+  }
+
+  // Check if any criteria use semantic weights
+  const hasSemanticWeights = ruleSet.criteria.some(c => isSemanticPriority(c.weight));
+
+  // Compile criteria (converts semantic weights to numeric)
+  const compiledCriteria = ruleSet.criteria.map(compileCriterion);
+
+  // Normalize weights to sum to 1.0
+  // This is always done now to support semantic weights and mixed weight types
+  if (hasSemanticWeights) {
+    // Semantic weights: always normalize
+    normalizeWeights(compiledCriteria);
+  } else {
+    // Numeric weights: validate they sum to ~1.0, then normalize for precision
+    const totalWeight = compiledCriteria.reduce((sum, c) => sum + c.weight, 0);
+    if (Math.abs(totalWeight - 1.0) > 0.01) {
+      throw new Error(`Criterion weights must sum to 1.0, got ${totalWeight.toFixed(4)}`);
+    }
+    // Normalize for floating point precision
+    normalizeWeights(compiledCriteria);
+  }
+
+  // Validate that all rules reference valid criteria
+  const criterionIds = new Set(compiledCriteria.map(c => c.id));
+  for (const rule of ruleSet.rules) {
+    if (!criterionIds.has(rule.criterion)) {
+      throw new Error(`Rule "${rule.id}" references unknown criterion "${rule.criterion}"`);
+    }
+  }
+
+  const config: UtilityConfig = {
+    mode: 'utility',
+    normalization: ruleSet.config?.normalization ?? 'min-max',
+    aggregation: ruleSet.config?.aggregation ?? 'weighted-sum'
+  };
+
+  return {
+    id: ruleSet.id,
+    name: ruleSet.name,
+    mode: 'utility',
+    schema: ruleSet.shape ? normalizeShape(ruleSet.shape) : { type: 'object' },
+    criteria: compiledCriteria,
+    rules: ruleSet.rules.map((rule, index) => compileUtilityRule(rule, index)),
+    config
+  };
+}

package/src/engines/utility/engine.ts

@@ -0,0 +1,200 @@
+/**
+ * Utility/MCDM Engine
+ *
+ * Self-contained engine for Multi-Criteria Decision Making.
+ * Compares multiple alternatives across weighted criteria to find the best option.
+ *
+ * Key difference from Scoring Engine:
+ * - Scoring: evaluates ONE item and produces a score
+ * - Utility: compares MULTIPLE alternatives and ranks them
+ */
+
+import {
+  IRuleEngine,
+  WorkingMemory,
+  Fact,
+  FactInput,
+  FactChange
+} from '../../core';
+
+import {
+  CompiledUtilityRuleSet,
+  UtilityOptions,
+  UtilityResult
+} from './types';
+
+import { UtilityStrategy } from './strategy';
+
+/**
+ * Alternative input - convenience type for adding alternatives
+ */
+export type AlternativeInput = {
+  id?: string;
+  name: string;
+  data: Record<string, any>;
+};
+
+/**
+ * Extended options that include the alternative type
+ */
+export type UtilityExecuteOptions = UtilityOptions & {
+  /** The fact type to treat as alternatives (required) */
+  alternativeType: string;
+};
+
+/**
+ * Utility/MCDM rule engine.
+ *
+ * Evaluates multiple alternatives across weighted criteria and ranks them
+ * by their overall utility score.
+ *
+ * @example
+ * ```typescript
+ * const engine = new UtilityEngine();
+ *
+ * // Add alternatives
+ * engine.addAlternative('JobOffer', {
+ *   name: 'TechCorp',
+ *   baseSalary: 150000,
+ *   remotePolicy: 'hybrid'
+ * });
+ * engine.addAlternative('JobOffer', {
+ *   name: 'StartupXYZ',
+ *   baseSalary: 130000,
+ *   remotePolicy: 'full'
+ * });
+ *
+ * const result = engine.execute(compiledRules, { alternativeType: 'JobOffer' });
+ * console.log(`Best option: ${result.winner?.name}`);
+ * ```
+ */
+export class UtilityEngine implements IRuleEngine<CompiledUtilityRuleSet, UtilityExecuteOptions, UtilityResult> {
+  private wm: WorkingMemory;
+  private strategy: UtilityStrategy;
+
+  constructor(workingMemory?: WorkingMemory) {
+    this.wm = workingMemory ?? new WorkingMemory();
+    this.strategy = new UtilityStrategy();
+  }
+
+  // ========================================
+  // IWorkingMemory Implementation
+  // ========================================
+
+  add(input: FactInput): Fact {
+    return this.wm.add(input);
+  }
+
+  remove(factId: string): Fact | undefined {
+    return this.wm.remove(factId);
+  }
+
+  update(input: FactInput): Fact {
+    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();
+  }
+
+  // ========================================
+  // Utility-Specific Methods
+  // ========================================
+
+  /**
+   * Add an alternative to compare.
+   *
+   * Convenience method that creates a fact with the given type and data.
+   *
+   * @param type - The type of alternative (e.g., 'JobOffer', 'Vendor', 'House')
+   * @param alternative - The alternative data including a name
+   * @returns The created fact
+   *
+   * @example
+   * ```typescript
+   * engine.addAlternative('JobOffer', {
+   *   name: 'TechCorp',
+   *   salary: 150000,
+   *   benefits: 'excellent'
+   * });
+   * ```
+   */
+  addAlternative(type: string, alternative: AlternativeInput): Fact {
+    return this.wm.add({
+      id: alternative.id,
+      type,
+      data: {
+        name: alternative.name,
+        ...alternative.data
+      }
+    });
+  }
+
+  /**
+   * Get all alternatives of a given type.
+   *
+   * @param type - The type of alternatives to retrieve
+   * @returns Array of facts representing alternatives
+   */
+  getAlternatives(type: string): Fact[] {
+    return this.wm.getByType(type);
+  }
+
+  // ========================================
+  // IRuleEngine Implementation
+  // ========================================
+
+  /**
+   * Execute a utility ruleset to compare alternatives.
+   *
+   * All alternatives of the specified type are evaluated against each criterion,
+   * normalized, weighted, and ranked by their overall utility score.
+   *
+   * @param ruleSet - Compiled utility ruleset
+   * @param options - Runtime options including alternativeType (required)
+   * @returns Result with ranked alternatives and optional sensitivity analysis
+   */
+  execute(ruleSet: CompiledUtilityRuleSet, options: UtilityExecuteOptions): UtilityResult {
+    if (!options.alternativeType) {
+      throw new Error('UtilityEngine.execute requires options.alternativeType');
+    }
+
+    return this.strategy.run(ruleSet, this.wm, options.alternativeType, options);
+  }
+
+  // ========================================
+  // Utility Methods
+  // ========================================
+
+  getWorkingMemory(): WorkingMemory {
+    return this.wm;
+  }
+}

package/src/engines/utility/index.ts

@@ -0,0 +1,53 @@
+/**
+ * Utility/MCDM Engine
+ *
+ * Provides Multi-Criteria Decision Making for comparing alternatives
+ * across weighted criteria. Use this when you need to rank multiple
+ * options based on trade-offs between different factors.
+ *
+ * Key difference from Scoring Engine:
+ * - Scoring: evaluates ONE item and produces a score
+ * - Utility: compares MULTIPLE alternatives and ranks them
+ */
+
+// Types
+export type {
+  // Semantic priority types
+  SemanticPriority,
+  // Criterion types
+  UtilityCriterion,
+  CompiledUtilityCriterion,
+  // Source types
+  UtilityRule,
+  UtilityRuleSet,
+  UtilityConfig,
+  // Compiled types
+  CompiledUtilityRule,
+  CompiledUtilityRuleSet,
+  // Runtime types
+  AlternativeResult,
+  SensitivityInfo,
+  UtilityOptions,
+  UtilityResult
+} from './types';
+
+// Semantic priority utilities
+export {
+  SEMANTIC_PRIORITY_VALUES,
+  isSemanticPriority
+} from './types';
+
+// Compiler
+export {
+  compileUtilityRule,
+  compileUtilityRuleSet
+} from './compiler';
+
+// Strategy
+export {
+  UtilityStrategy,
+  utilityStrategy
+} from './strategy';
+
+// Engine
+export { UtilityEngine, AlternativeInput, UtilityExecuteOptions } from './engine';