@higher.archi/boe 1.0.0

package/src/engines/constraint/strategy.ts

@@ -0,0 +1,725 @@
+/**
+ * Constraint Satisfaction Engine Strategy
+ *
+ * Implements backtracking search with constraint propagation.
+ * Uses MRV (Minimum Remaining Values) heuristic for variable ordering.
+ */
+
+import { evaluateCondition } from '../../core';
+import { IWorkingMemory } from '../../core/memory';
+import { Fact } from '../../core/types/fact';
+
+import {
+  CompiledConstraintRuleSet,
+  CompiledConstraintVariable,
+  CompiledConstraint,
+  CompiledPreference,
+  ConstraintOptions,
+  ConstraintResult,
+  ConstraintAllResult,
+  Assignment,
+  SearchStats,
+  ConflictInfo,
+  ScoredSolution
+} from './types';
+
+// ========================================
+// Search State
+// ========================================
+
+interface SearchState {
+  // Current (partial) assignment
+  assignment: (any | undefined)[];  // Index corresponds to variable index
+
+  // Remaining domain for each variable (pruned during search)
+  domains: any[][];
+
+  // Which variables have been assigned
+  assigned: boolean[];
+
+  // Statistics
+  stats: SearchStats;
+
+  // Timing
+  startTime: number;
+
+  // Configuration
+  maxIterations: number;
+  timeout: number;
+}
+
+// ========================================
+// Constraint Checking
+// ========================================
+
+/**
+ * Check if a constraint is satisfied given current assignments.
+ * Returns true if satisfied, false if violated, undefined if can't be evaluated yet.
+ */
+function checkConstraint(
+  constraint: CompiledConstraint,
+  state: SearchState,
+  variables: CompiledConstraintVariable[],
+  factContext: Record<string, Fact>
+): boolean | undefined {
+  // Build binding context with assigned values
+  const bindingContext: Record<string, Fact> = { ...factContext };
+
+  // Check if all variables for this constraint are assigned
+  for (const varIndex of constraint.variableIndices) {
+    if (!state.assigned[varIndex]) {
+      // Can't evaluate yet - not all variables assigned
+      return undefined;
+    }
+
+    const variable = variables[varIndex];
+    const value = state.assignment[varIndex];
+
+    // Create a pseudo-fact for the variable
+    // If value is an object, use it as data; otherwise wrap it
+    const data = (typeof value === 'object' && value !== null) ? value : value;
+    bindingContext[variable.name] = {
+      id: variable.name,
+      type: '_variable',
+      data: data as Record<string, any>
+    };
+  }
+
+  // Evaluate the constraint condition
+  try {
+    return evaluateCondition(constraint.condition, bindingContext);
+  } catch (e) {
+    // If evaluation fails, treat as violated
+    return false;
+  }
+}
+
+/**
+ * Check all constraints involving a specific variable.
+ * Returns list of violated constraint IDs, or empty if all satisfied.
+ */
+function checkConstraintsForVariable(
+  varIndex: number,
+  state: SearchState,
+  ruleSet: CompiledConstraintRuleSet,
+  factContext: Record<string, Fact>
+): ConflictInfo[] {
+  const conflicts: ConflictInfo[] = [];
+  const constraintIndices = ruleSet.constraintsByVariable.get(varIndex) ?? [];
+
+  for (const ci of constraintIndices) {
+    const constraint = ruleSet.constraints[ci];
+    const result = checkConstraint(constraint, state, ruleSet.variables, factContext);
+
+    if (result === false) {
+      // Constraint violated
+      const values: Record<string, any> = {};
+      for (const vi of constraint.variableIndices) {
+        if (state.assigned[vi]) {
+          values[ruleSet.variables[vi].name] = state.assignment[vi];
+        }
+      }
+
+      conflicts.push({
+        constraintId: constraint.id,
+        constraintName: constraint.name,
+        variables: constraint.variableNames,
+        values
+      });
+    }
+  }
+
+  return conflicts;
+}
+
+// ========================================
+// Variable Ordering (MRV Heuristic)
+// ========================================
+
+/**
+ * Select the next unassigned variable using MRV (Minimum Remaining Values).
+ * This heuristic picks the variable with the smallest remaining domain,
+ * which helps fail fast and prune the search space.
+ */
+function selectUnassignedVariable(
+  state: SearchState,
+  ruleSet: CompiledConstraintRuleSet
+): number | undefined {
+  let bestIndex: number | undefined;
+  let bestDomainSize = Infinity;
+
+  for (let i = 0; i < ruleSet.variables.length; i++) {
+    if (!state.assigned[i]) {
+      const domainSize = state.domains[i].length;
+
+      // If domain is empty, this path is impossible
+      if (domainSize === 0) {
+        return i;  // Return it so we can backtrack
+      }
+
+      if (domainSize < bestDomainSize) {
+        bestDomainSize = domainSize;
+        bestIndex = i;
+      }
+    }
+  }
+
+  return bestIndex;
+}
+
+/**
+ * Static variable ordering - just pick the first unassigned.
+ */
+function selectUnassignedVariableStatic(
+  state: SearchState,
+  ruleSet: CompiledConstraintRuleSet
+): number | undefined {
+  for (let i = 0; i < ruleSet.variables.length; i++) {
+    if (!state.assigned[i]) {
+      return i;
+    }
+  }
+  return undefined;
+}
+
+// ========================================
+// Forward Checking (Domain Pruning)
+// ========================================
+
+/**
+ * After assigning a variable, prune inconsistent values from neighboring domains.
+ * Returns true if all domains still have values, false if any domain is emptied.
+ */
+function forwardCheck(
+  assignedVarIndex: number,
+  state: SearchState,
+  ruleSet: CompiledConstraintRuleSet,
+  factContext: Record<string, Fact>
+): boolean {
+  const constraintIndices = ruleSet.constraintsByVariable.get(assignedVarIndex) ?? [];
+
+  for (const ci of constraintIndices) {
+    const constraint = ruleSet.constraints[ci];
+
+    // Find unassigned variables in this constraint
+    for (const varIndex of constraint.variableIndices) {
+      if (state.assigned[varIndex]) continue;
+
+      // Try each value in the domain
+      const validValues: any[] = [];
+      for (const value of state.domains[varIndex]) {
+        // Temporarily assign
+        state.assignment[varIndex] = value;
+        state.assigned[varIndex] = true;
+
+        // Check constraint
+        const result = checkConstraint(constraint, state, ruleSet.variables, factContext);
+
+        // Unassign
+        state.assignment[varIndex] = undefined;
+        state.assigned[varIndex] = false;
+
+        // Keep value if constraint is satisfied or can't be evaluated yet
+        if (result !== false) {
+          validValues.push(value);
+        } else {
+          state.stats.pruned++;
+        }
+      }
+
+      state.domains[varIndex] = validValues;
+
+      // If domain is empty, forward check failed
+      if (validValues.length === 0) {
+        return false;
+      }
+    }
+  }
+
+  return true;
+}
+
+// ========================================
+// Backtracking Search
+// ========================================
+
+/**
+ * Recursive backtracking search.
+ * Returns true if a solution is found.
+ */
+function backtrack(
+  state: SearchState,
+  ruleSet: CompiledConstraintRuleSet,
+  factContext: Record<string, Fact>,
+  options: ConstraintOptions,
+  useForwardCheck: boolean
+): boolean {
+  // Check limits
+  state.stats.iterations++;
+  state.stats.elapsed = Date.now() - state.startTime;
+
+  if (state.stats.iterations >= state.maxIterations) {
+    return false;
+  }
+
+  if (state.stats.elapsed >= state.timeout) {
+    return false;
+  }
+
+  // Select next variable
+  const selectVar = ruleSet.config.variableOrdering === 'mrv'
+    ? selectUnassignedVariable
+    : selectUnassignedVariableStatic;
+
+  const varIndex = selectVar(state, ruleSet);
+
+  // If no unassigned variables, we have a solution
+  if (varIndex === undefined) {
+    return true;
+  }
+
+  const variable = ruleSet.variables[varIndex];
+  const domain = state.domains[varIndex];
+
+  // If domain is empty, backtrack
+  if (domain.length === 0) {
+    return false;
+  }
+
+  // Save domain state for backtracking
+  const savedDomains = state.domains.map(d => [...d]);
+
+  // Try each value in the domain
+  for (const value of domain) {
+    // Assign value
+    state.assignment[varIndex] = value;
+    state.assigned[varIndex] = true;
+
+    // Callback
+    if (options.onAssign) {
+      options.onAssign(variable.name, value);
+    }
+
+    // Check constraints
+    const conflicts = checkConstraintsForVariable(varIndex, state, ruleSet, factContext);
+
+    if (conflicts.length === 0) {
+      // No immediate conflicts
+
+      // Forward check if enabled
+      let consistent = true;
+      if (useForwardCheck) {
+        consistent = forwardCheck(varIndex, state, ruleSet, factContext);
+      }
+
+      if (consistent) {
+        // Recurse
+        if (backtrack(state, ruleSet, factContext, options, useForwardCheck)) {
+          return true;
+        }
+      }
+    }
+
+    // Backtrack
+    state.assignment[varIndex] = undefined;
+    state.assigned[varIndex] = false;
+    state.domains = savedDomains.map(d => [...d]);  // Restore domains
+    state.stats.backtracks++;
+
+    if (options.onBacktrack) {
+      options.onBacktrack(variable.name);
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Search for all solutions up to a limit.
+ */
+function backtrackAll(
+  state: SearchState,
+  ruleSet: CompiledConstraintRuleSet,
+  factContext: Record<string, Fact>,
+  options: ConstraintOptions,
+  solutions: Assignment[],
+  maxSolutions: number,
+  useForwardCheck: boolean
+): void {
+  // Check limits
+  state.stats.iterations++;
+  state.stats.elapsed = Date.now() - state.startTime;
+
+  if (state.stats.iterations >= state.maxIterations) {
+    return;
+  }
+
+  if (state.stats.elapsed >= state.timeout) {
+    return;
+  }
+
+  if (solutions.length >= maxSolutions) {
+    return;
+  }
+
+  // Select next variable
+  const selectVar = ruleSet.config.variableOrdering === 'mrv'
+    ? selectUnassignedVariable
+    : selectUnassignedVariableStatic;
+
+  const varIndex = selectVar(state, ruleSet);
+
+  // If no unassigned variables, we have a solution
+  if (varIndex === undefined) {
+    // Build assignment object
+    const assignment: Assignment = {};
+    for (let i = 0; i < ruleSet.variables.length; i++) {
+      assignment[ruleSet.variables[i].name] = state.assignment[i];
+    }
+    solutions.push(assignment);
+
+    if (options.onSolution) {
+      options.onSolution(assignment);
+    }
+    return;
+  }
+
+  const variable = ruleSet.variables[varIndex];
+  const domain = state.domains[varIndex];
+
+  if (domain.length === 0) {
+    return;
+  }
+
+  const savedDomains = state.domains.map(d => [...d]);
+
+  for (const value of domain) {
+    state.assignment[varIndex] = value;
+    state.assigned[varIndex] = true;
+
+    if (options.onAssign) {
+      options.onAssign(variable.name, value);
+    }
+
+    const conflicts = checkConstraintsForVariable(varIndex, state, ruleSet, factContext);
+
+    if (conflicts.length === 0) {
+      let consistent = true;
+      if (useForwardCheck) {
+        consistent = forwardCheck(varIndex, state, ruleSet, factContext);
+      }
+
+      if (consistent) {
+        backtrackAll(state, ruleSet, factContext, options, solutions, maxSolutions, useForwardCheck);
+      }
+    }
+
+    state.assignment[varIndex] = undefined;
+    state.assigned[varIndex] = false;
+    state.domains = savedDomains.map(d => [...d]);
+    state.stats.backtracks++;
+
+    if (options.onBacktrack) {
+      options.onBacktrack(variable.name);
+    }
+
+    // Check if we've found enough solutions
+    if (solutions.length >= maxSolutions) {
+      return;
+    }
+  }
+}
+
+// ========================================
+// Preference Scoring
+// ========================================
+
+/**
+ * Check if a preference is satisfied for a given assignment.
+ */
+function checkPreference(
+  preference: CompiledPreference,
+  assignment: Assignment,
+  variables: CompiledConstraintVariable[],
+  factContext: Record<string, Fact>
+): boolean {
+  // Build binding context with assigned values
+  const bindingContext: Record<string, Fact> = { ...factContext };
+
+  // Add all variable values to context
+  for (const varIndex of preference.variableIndices) {
+    const variable = variables[varIndex];
+    const value = assignment[variable.name];
+
+    // Create a pseudo-fact for the variable
+    const data = (typeof value === 'object' && value !== null) ? value : value;
+    bindingContext[variable.name] = {
+      id: variable.name,
+      type: '_variable',
+      data: data as Record<string, any>
+    };
+  }
+
+  // Evaluate the preference condition
+  try {
+    return evaluateCondition(preference.condition, bindingContext);
+  } catch (e) {
+    // If evaluation fails, treat as not satisfied
+    return false;
+  }
+}
+
+/**
+ * Score a solution against all preferences.
+ * Returns the total score and list of satisfied preference IDs.
+ */
+function scoreSolution(
+  assignment: Assignment,
+  ruleSet: CompiledConstraintRuleSet,
+  factContext: Record<string, Fact>
+): { score: number; satisfiedPreferences: string[] } {
+  let score = 0;
+  const satisfiedPreferences: string[] = [];
+
+  for (const preference of ruleSet.preferences) {
+    if (checkPreference(preference, assignment, ruleSet.variables, factContext)) {
+      score += preference.weight;
+      satisfiedPreferences.push(preference.id);
+    }
+  }
+
+  return { score, satisfiedPreferences };
+}
+
+/**
+ * Rank solutions by preference score.
+ * For 'maximize', higher scores come first.
+ * For 'minimize', lower scores come first.
+ */
+function rankSolutions(
+  solutions: Assignment[],
+  ruleSet: CompiledConstraintRuleSet,
+  factContext: Record<string, Fact>,
+  optimize: 'maximize' | 'minimize'
+): ScoredSolution[] {
+  // Score each solution
+  const scored: ScoredSolution[] = solutions.map(assignment => {
+    const { score, satisfiedPreferences } = scoreSolution(assignment, ruleSet, factContext);
+    return { assignment, score, satisfiedPreferences };
+  });
+
+  // Sort by score
+  if (optimize === 'maximize') {
+    scored.sort((a, b) => b.score - a.score);  // Descending
+  } else {
+    scored.sort((a, b) => a.score - b.score);  // Ascending
+  }
+
+  return scored;
+}
+
+// ========================================
+// Strategy Implementation
+// ========================================
+
+export class ConstraintStrategy {
+  /**
+   * Find one solution that satisfies all constraints.
+   * When optimization is enabled, finds the best solution by preference score.
+   */
+  solve(
+    ruleSet: CompiledConstraintRuleSet,
+    wm: IWorkingMemory,
+    options: ConstraintOptions = {}
+  ): ConstraintResult {
+    const startTime = performance.now();
+    const config = ruleSet.config;
+
+    // Build fact context from working memory
+    const factContext: Record<string, Fact> = {};
+    for (const input of ruleSet.inputs) {
+      const facts = wm.getByType(input.type);
+      if (facts.length > 0) {
+        factContext[input.name] = facts[0];
+      }
+    }
+
+    // If optimization is enabled, use solveAll and return the best
+    if (config.optimize !== 'none' && ruleSet.preferences.length > 0) {
+      const allResult = this.solveAll(ruleSet, wm, options);
+
+      if (allResult.solutions.length === 0) {
+        return {
+          solved: false,
+          conflicts: [],
+          stats: allResult.stats,
+          exhausted: !allResult.timedOut,
+          timedOut: allResult.timedOut,
+          executionTimeMs: allResult.executionTimeMs
+        };
+      }
+
+      // Get the best solution (first in ranked list)
+      const ranked = allResult.rankedSolutions!;
+      const best = ranked[0];
+
+      return {
+        solved: true,
+        assignment: best.assignment,
+        score: best.score,
+        satisfiedPreferences: best.satisfiedPreferences,
+        stats: allResult.stats,
+        exhausted: allResult.complete,
+        timedOut: allResult.timedOut,
+        executionTimeMs: allResult.executionTimeMs
+      };
+    }
+
+    // Standard solve without optimization
+    const state: SearchState = {
+      assignment: new Array(ruleSet.variables.length).fill(undefined),
+      domains: ruleSet.variables.map(v => [...v.domain]),
+      assigned: new Array(ruleSet.variables.length).fill(false),
+      stats: {
+        iterations: 0,
+        backtracks: 0,
+        pruned: 0,
+        elapsed: 0
+      },
+      startTime: Date.now(),
+      maxIterations: options.maxIterations ?? config.maxIterations,
+      timeout: options.timeout ?? config.timeout
+    };
+
+    // Use forward checking for 'forward-check' strategy
+    const useForwardCheck = config.strategy === 'forward-check';
+
+    // Run search
+    const found = backtrack(state, ruleSet, factContext, options, useForwardCheck);
+
+    // Update elapsed time
+    state.stats.elapsed = Date.now() - state.startTime;
+
+    // Build result
+    if (found) {
+      const assignment: Assignment = {};
+      for (let i = 0; i < ruleSet.variables.length; i++) {
+        assignment[ruleSet.variables[i].name] = state.assignment[i];
+      }
+
+      const executionTimeMs = Math.round((performance.now() - startTime) * 100) / 100;
+
+      // Score the solution if preferences exist (even without optimize mode)
+      let score: number | undefined;
+      let satisfiedPreferences: string[] | undefined;
+      if (ruleSet.preferences.length > 0) {
+        const scoring = scoreSolution(assignment, ruleSet, factContext);
+        score = scoring.score;
+        satisfiedPreferences = scoring.satisfiedPreferences;
+      }
+
+      return {
+        solved: true,
+        assignment,
+        score,
+        satisfiedPreferences,
+        stats: state.stats,
+        exhausted: false,
+        timedOut: false,
+        executionTimeMs
+      };
+    }
+
+    // No solution found - determine why
+    const timedOut = state.stats.elapsed >= state.timeout;
+    const exhausted = !timedOut && state.stats.iterations < state.maxIterations;
+
+    // Try to identify conflicts (last attempted assignment)
+    const conflicts: ConflictInfo[] = [];
+    // Could enhance this to track the actual failing constraints
+
+    const executionTimeMs = Math.round((performance.now() - startTime) * 100) / 100;
+    return {
+      solved: false,
+      conflicts,
+      stats: state.stats,
+      exhausted,
+      timedOut,
+      executionTimeMs
+    };
+  }
+
+  /**
+   * Find all solutions up to a limit.
+   * When optimization is enabled, returns solutions ranked by preference score.
+   */
+  solveAll(
+    ruleSet: CompiledConstraintRuleSet,
+    wm: IWorkingMemory,
+    options: ConstraintOptions = {}
+  ): ConstraintAllResult {
+    const startTime = performance.now();
+    const config = ruleSet.config;
+
+    // Build fact context
+    const factContext: Record<string, Fact> = {};
+    for (const input of ruleSet.inputs) {
+      const facts = wm.getByType(input.type);
+      if (facts.length > 0) {
+        factContext[input.name] = facts[0];
+      }
+    }
+
+    // Initialize search state
+    const state: SearchState = {
+      assignment: new Array(ruleSet.variables.length).fill(undefined),
+      domains: ruleSet.variables.map(v => [...v.domain]),
+      assigned: new Array(ruleSet.variables.length).fill(false),
+      stats: {
+        iterations: 0,
+        backtracks: 0,
+        pruned: 0,
+        elapsed: 0
+      },
+      startTime: Date.now(),
+      maxIterations: options.maxIterations ?? config.maxIterations,
+      timeout: options.timeout ?? config.timeout
+    };
+
+    const maxSolutions = options.maxSolutions ?? config.maxSolutions;
+    const solutions: Assignment[] = [];
+    const useForwardCheck = config.strategy === 'forward-check';
+
+    // Run search
+    backtrackAll(state, ruleSet, factContext, options, solutions, maxSolutions, useForwardCheck);
+
+    // Update elapsed time
+    state.stats.elapsed = Date.now() - state.startTime;
+
+    // Determine if search completed
+    const timedOut = state.stats.elapsed >= state.timeout;
+    const hitIterationLimit = state.stats.iterations >= state.maxIterations;
+    const hitSolutionLimit = solutions.length >= maxSolutions;
+    const complete = !timedOut && !hitIterationLimit && !hitSolutionLimit;
+
+    const executionTimeMs = Math.round((performance.now() - startTime) * 100) / 100;
+
+    // Rank solutions by preference score if optimization is enabled
+    let rankedSolutions: ScoredSolution[] | undefined;
+    if (config.optimize !== 'none' && ruleSet.preferences.length > 0 && solutions.length > 0) {
+      rankedSolutions = rankSolutions(solutions, ruleSet, factContext, config.optimize);
+    }
+
+    return {
+      solutions,
+      rankedSolutions,
+      complete,
+      stats: state.stats,
+      timedOut,
+      executionTimeMs
+    };
+  }
+}
+
+// Export singleton instance
+export const constraintStrategy = new ConstraintStrategy();