@higher.archi/boe 1.0.0

package/src/engines/constraint/compiler.ts

@@ -0,0 +1,267 @@
+/**
+ * Constraint Satisfaction Engine Compiler
+ *
+ * Compiles constraint rulesets into an optimized format for solving.
+ * Builds constraint graph for efficient propagation.
+ */
+
+import {
+  compileCondition,
+  normalizeShape,
+  CompiledInputParameter
+} from '../../core';
+
+import {
+  ConstraintRuleSet,
+  ConstraintConfig,
+  CompiledConstraintRuleSet,
+  CompiledConstraintVariable,
+  CompiledConstraint,
+  CompiledPreference,
+  ConstraintVariable,
+  Constraint,
+  Preference,
+  PreferenceWeight,
+  SEMANTIC_WEIGHTS
+} from './types';
+
+// ========================================
+// Default Configuration
+// ========================================
+
+const DEFAULT_CONFIG: ConstraintConfig = {
+  mode: 'constraint',
+  strategy: 'backtrack',
+  variableOrdering: 'mrv',      // Minimum Remaining Values (fail-fast)
+  valueOrdering: 'static',
+  maxIterations: 100000,
+  maxSolutions: 100,
+  timeout: 30000,
+  optimize: 'none'              // No optimization by default (backwards compatible)
+};
+
+// ========================================
+// Variable Compilation
+// ========================================
+
+function compileVariable(
+  variable: ConstraintVariable,
+  index: number
+): CompiledConstraintVariable {
+  if (!variable.name) {
+    throw new Error(`Variable at index ${index} must have a name`);
+  }
+
+  if (!Array.isArray(variable.domain) || variable.domain.length === 0) {
+    throw new Error(`Variable '${variable.name}' must have a non-empty domain array`);
+  }
+
+  return {
+    name: variable.name,
+    domain: [...variable.domain],  // Copy to prevent mutation
+    index
+  };
+}
+
+// ========================================
+// Constraint Compilation
+// ========================================
+
+function compileConstraint(
+  constraint: Constraint,
+  variableMap: Map<string, number>,
+  constraintIndex: number
+): CompiledConstraint {
+  if (!constraint.id) {
+    throw new Error(`Constraint at index ${constraintIndex} must have an id`);
+  }
+
+  if (!Array.isArray(constraint.variables) || constraint.variables.length === 0) {
+    throw new Error(`Constraint '${constraint.id}' must reference at least one variable`);
+  }
+
+  // Map variable names to indices
+  const variableIndices: number[] = [];
+  for (const varName of constraint.variables) {
+    const index = variableMap.get(varName);
+    if (index === undefined) {
+      throw new Error(
+        `Constraint '${constraint.id}' references unknown variable '${varName}'`
+      );
+    }
+    variableIndices.push(index);
+  }
+
+  // Compile the constraint rule
+  const condition = compileCondition(constraint.rule);
+
+  return {
+    id: constraint.id,
+    name: constraint.name,
+    variableIndices,
+    variableNames: [...constraint.variables],
+    condition
+  };
+}
+
+// ========================================
+// Preference Compilation
+// ========================================
+
+/**
+ * Resolve a preference weight to its numeric value.
+ * Semantic weights are looked up in SEMANTIC_WEIGHTS.
+ */
+function resolveWeight(weight: PreferenceWeight): number {
+  if (typeof weight === 'number') {
+    return weight;
+  }
+  return SEMANTIC_WEIGHTS[weight];
+}
+
+function compilePreference(
+  preference: Preference,
+  variableMap: Map<string, number>,
+  preferenceIndex: number
+): CompiledPreference {
+  if (!preference.id) {
+    throw new Error(`Preference at index ${preferenceIndex} must have an id`);
+  }
+
+  if (!Array.isArray(preference.variables) || preference.variables.length === 0) {
+    throw new Error(`Preference '${preference.id}' must reference at least one variable`);
+  }
+
+  // Map variable names to indices
+  const variableIndices: number[] = [];
+  for (const varName of preference.variables) {
+    const index = variableMap.get(varName);
+    if (index === undefined) {
+      throw new Error(
+        `Preference '${preference.id}' references unknown variable '${varName}'`
+      );
+    }
+    variableIndices.push(index);
+  }
+
+  // Compile the preference rule
+  const condition = compileCondition(preference.rule);
+
+  // Resolve weight to numeric value
+  const weight = resolveWeight(preference.weight);
+
+  return {
+    id: preference.id,
+    name: preference.name,
+    variableIndices,
+    variableNames: [...preference.variables],
+    condition,
+    weight
+  };
+}
+
+// ========================================
+// Constraint Graph Building
+// ========================================
+
+/**
+ * Build a map from variable index to constraint indices.
+ * Used for efficient constraint propagation.
+ */
+function buildConstraintGraph(
+  variables: CompiledConstraintVariable[],
+  constraints: CompiledConstraint[]
+): Map<number, number[]> {
+  const graph = new Map<number, number[]>();
+
+  // Initialize empty arrays for each variable
+  for (const variable of variables) {
+    graph.set(variable.index, []);
+  }
+
+  // Add constraint indices to each involved variable
+  for (let ci = 0; ci < constraints.length; ci++) {
+    const constraint = constraints[ci];
+    for (const varIndex of constraint.variableIndices) {
+      graph.get(varIndex)!.push(ci);
+    }
+  }
+
+  return graph;
+}
+
+// ========================================
+// Input Parameter Compilation
+// ========================================
+
+function compileInputParameter(input: any): CompiledInputParameter {
+  return {
+    name: input.name,
+    type: input.type,
+    schema: input.shape ? normalizeShape(input.shape) : { type: 'object' as const }
+  };
+}
+
+// ========================================
+// RuleSet Compilation
+// ========================================
+
+export function compileConstraintRuleSet(
+  ruleSet: ConstraintRuleSet
+): CompiledConstraintRuleSet {
+  // Validate mode
+  if (ruleSet.mode !== 'constraint') {
+    throw new Error(`Expected mode 'constraint', got '${ruleSet.mode}'`);
+  }
+
+  // Compile variables and build name->index map
+  const variableMap = new Map<string, number>();
+  const compiledVariables = ruleSet.variables.map((variable, index) => {
+    const compiled = compileVariable(variable, index);
+
+    if (variableMap.has(variable.name)) {
+      throw new Error(`Duplicate variable name: '${variable.name}'`);
+    }
+    variableMap.set(variable.name, index);
+
+    return compiled;
+  });
+
+  // Compile constraints
+  const compiledConstraints = ruleSet.constraints.map((constraint, index) =>
+    compileConstraint(constraint, variableMap, index)
+  );
+
+  // Compile preferences (soft constraints)
+  const compiledPreferences = (ruleSet.preferences ?? []).map((preference, index) =>
+    compilePreference(preference, variableMap, index)
+  );
+
+  // Build constraint graph
+  const constraintsByVariable = buildConstraintGraph(
+    compiledVariables,
+    compiledConstraints
+  );
+
+  // Merge config with defaults
+  const config: ConstraintConfig = {
+    ...DEFAULT_CONFIG,
+    ...ruleSet.config
+  };
+
+  // Compile inputs (optional)
+  const inputs = (ruleSet.inputs ?? []).map(compileInputParameter);
+
+  return {
+    id: ruleSet.id,
+    name: ruleSet.name,
+    mode: 'constraint',
+    schema: ruleSet.shape ? normalizeShape(ruleSet.shape) : { type: 'object' as const },
+    inputs,
+    variables: compiledVariables,
+    constraints: compiledConstraints,
+    preferences: compiledPreferences,
+    constraintsByVariable,
+    config
+  };
+}

package/src/engines/constraint/engine.ts

@@ -0,0 +1,175 @@
+/**
+ * Constraint Satisfaction Engine
+ *
+ * Find valid assignments for variables that satisfy all constraints.
+ * Implements IRuleEngine with strongly-typed ruleset, options, and result.
+ */
+
+import {
+  IRuleEngine,
+  WorkingMemory,
+  Fact,
+  FactInput,
+  FactChange
+} from '../../core';
+
+import {
+  CompiledConstraintRuleSet,
+  ConstraintOptions,
+  ConstraintResult,
+  ConstraintAllResult
+} from './types';
+
+import { ConstraintStrategy } from './strategy';
+
+/**
+ * Constraint satisfaction engine.
+ *
+ * Finds valid assignments for variables that satisfy all constraints.
+ * Uses backtracking search with optional forward checking and MRV heuristic.
+ *
+ * @example
+ * ```typescript
+ * const engine = new ConstraintEngine();
+ *
+ * const result = engine.solve(compiledRules);
+ * if (result.solved) {
+ *   console.log(result.assignment);
+ *   // { room1: 'meeting-a', room2: 'meeting-b', ... }
+ * }
+ * ```
+ *
+ * @example Find all solutions
+ * ```typescript
+ * const result = engine.solveAll(compiledRules, { maxSolutions: 10 });
+ * console.log(`Found ${result.solutions.length} valid schedules`);
+ * ```
+ *
+ * @example With working memory for dynamic constraints
+ * ```typescript
+ * const engine = new ConstraintEngine();
+ * engine.add({ type: 'Room', data: { id: 'A', hasProjector: true } });
+ *
+ * const result = engine.solve(compiledRules);
+ * ```
+ */
+export class ConstraintEngine implements IRuleEngine<CompiledConstraintRuleSet, ConstraintOptions, ConstraintResult> {
+  private wm: WorkingMemory;
+  private strategy: ConstraintStrategy;
+
+  /**
+   * Create a new ConstraintEngine.
+   *
+   * @param workingMemory - Optional shared WorkingMemory. If not provided, creates its own.
+   */
+  constructor(workingMemory?: WorkingMemory) {
+    this.wm = workingMemory ?? new WorkingMemory();
+    this.strategy = new ConstraintStrategy();
+  }
+
+  // ========================================
+  // 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();
+  }
+
+  // ========================================
+  // IRuleEngine Implementation
+  // ========================================
+
+  /**
+   * Find one solution that satisfies all constraints.
+   * Alias for solve() to match IRuleEngine interface.
+   *
+   * @param ruleSet - Compiled constraint ruleset
+   * @param options - Runtime options (callbacks, limits)
+   * @returns Result with solution or conflict information
+   */
+  execute(ruleSet: CompiledConstraintRuleSet, options: ConstraintOptions = {}): ConstraintResult {
+    return this.solve(ruleSet, options);
+  }
+
+  // ========================================
+  // Constraint-Specific Methods
+  // ========================================
+
+  /**
+   * Find one solution that satisfies all constraints.
+   *
+   * Uses backtracking search with MRV (Minimum Remaining Values) heuristic
+   * for variable ordering. Optionally uses forward checking for constraint
+   * propagation.
+   *
+   * @param ruleSet - Compiled constraint ruleset
+   * @param options - Runtime options (callbacks, limits)
+   * @returns Result with solution or conflict information
+   */
+  solve(ruleSet: CompiledConstraintRuleSet, options: ConstraintOptions = {}): ConstraintResult {
+    return this.strategy.solve(ruleSet, this.wm, options);
+  }
+
+  /**
+   * Find all solutions that satisfy all constraints, up to a limit.
+   *
+   * @param ruleSet - Compiled constraint ruleset
+   * @param options - Runtime options (maxSolutions, callbacks, limits)
+   * @returns Result with array of solutions
+   */
+  solveAll(ruleSet: CompiledConstraintRuleSet, options: ConstraintOptions = {}): ConstraintAllResult {
+    return this.strategy.solveAll(ruleSet, this.wm, options);
+  }
+
+  // ========================================
+  // Utility Methods
+  // ========================================
+
+  /**
+   * Get the underlying WorkingMemory instance.
+   * Useful for sharing memory between multiple engines.
+   */
+  getWorkingMemory(): WorkingMemory {
+    return this.wm;
+  }
+}

package/src/engines/constraint/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Constraint Satisfaction Engine
+ *
+ * Find valid assignments for variables that satisfy all constraints.
+ * Uses backtracking search with MRV heuristic and optional forward checking.
+ */
+
+// Types
+export * from './types';
+
+// Compiler
+export { compileConstraintRuleSet } from './compiler';
+
+// Engine
+export { ConstraintEngine } from './engine';
+
+// Strategy (for advanced usage)
+export { ConstraintStrategy, constraintStrategy } from './strategy';