@higher.archi/boe 1.0.0

package/src/engines/constraint/types.ts

@@ -0,0 +1,415 @@
+/**
+ * Constraint Satisfaction Engine Types
+ *
+ * Think of this like solving a puzzle where you have boxes (variables) that need
+ * to be filled with values, but certain combinations aren't allowed. For example:
+ * "Alice and Bob can't both work the morning shift" or "Meeting A and Meeting B
+ * can't be in the same room at 9am."
+ *
+ * The engine tries different combinations until it finds one where all the rules
+ * (constraints) are satisfied—or tells you no valid combination exists.
+ */
+
+import {
+  BaseRuleSet,
+  CompiledBaseRuleSet,
+  CompiledCondition,
+  Condition,
+  InputParameter,
+  CompiledInputParameter
+} from '../../core';
+
+// ========================================
+// Source Types (User-Defined)
+// ========================================
+
+/**
+ * A variable to solve for.
+ *
+ * Think of this as a blank to fill in. The "domain" is the list of possible
+ * answers. For example: if you're scheduling shifts, a variable might be
+ * "monday_morning" and the domain might be ['Alice', 'Bob', 'Carol']—the
+ * people who could work that shift.
+ *
+ * The engine's job is to pick one value from each variable's domain such
+ * that all constraints are satisfied.
+ */
+export type ConstraintVariable = {
+  name: string;          // Variable name (referenced as $name in constraints)
+  domain: any[];         // Possible values this variable can take
+  description?: string;  // Human-readable description
+};
+
+/**
+ * A constraint that must be satisfied.
+ *
+ * This is a rule that says "these values can't go together" or "these values
+ * must satisfy this condition." For example: "The person on monday_morning
+ * can't be the same as the person on monday_evening" (no double shifts).
+ *
+ * Constraints reference variables by name and use the standard expression
+ * syntax: ['notEqual', '$monday_morning', '$monday_evening']
+ */
+export type Constraint = {
+  id: string;             // Unique identifier
+  name?: string;          // Human-readable name
+  variables: string[];    // Which variables this constraint involves
+  rule: Condition;        // Must evaluate true for valid assignment
+};
+
+// ========================================
+// Soft Constraints (Preferences)
+// ========================================
+
+/**
+ * Semantic weight values for preferences.
+ *
+ * These provide human-readable alternatives to numeric weights,
+ * making rulesets more intuitive to read and maintain.
+ */
+export type SemanticWeight =
+  | 'critical'        // 100 - Almost a hard constraint
+  | 'very-important'  // 50  - Strong preference
+  | 'important'       // 25  - Meaningful preference
+  | 'nice-to-have'    // 10  - Would be good if possible
+  | 'slight'          // 5   - Minor preference
+  | 'tiebreaker';     // 1   - Only matters when scores are equal
+
+/**
+ * Mapping of semantic weights to numeric values.
+ */
+export const SEMANTIC_WEIGHTS: Record<SemanticWeight, number> = {
+  'critical': 100,
+  'very-important': 50,
+  'important': 25,
+  'nice-to-have': 10,
+  'slight': 5,
+  'tiebreaker': 1
+};
+
+/**
+ * Weight for a preference - can be numeric or semantic.
+ */
+export type PreferenceWeight = number | SemanticWeight;
+
+/**
+ * A soft constraint (preference) that influences solution ranking.
+ *
+ * Unlike hard constraints which must be satisfied, preferences are optional
+ * and contribute to a solution's score when satisfied. Solutions are ranked
+ * by their total preference score.
+ *
+ * @example
+ * // Prefer high floors (10 points when satisfied)
+ * {
+ *   id: 'high-floor',
+ *   variables: ['room'],
+ *   rule: ['greaterThanOrEquals', '$room.floor', 15],
+ *   weight: 'nice-to-have'  // or weight: 10
+ * }
+ */
+export type Preference = {
+  id: string;                 // Unique identifier
+  name?: string;              // Human-readable name
+  variables: string[];        // Which variables this preference involves
+  rule: Condition;            // Condition that makes this preference satisfied
+  weight: PreferenceWeight;   // Points added when satisfied
+};
+
+/**
+ * Constraint satisfaction ruleset.
+ *
+ * The complete problem definition: what blanks need to be filled (variables),
+ * what values are allowed in each blank (domains), and what rules must be
+ * followed (constraints). Optionally includes soft preferences for optimization.
+ */
+export type ConstraintRuleSet = BaseRuleSet & {
+  mode: 'constraint';
+
+  // Facts from working memory (optional - for dynamic domains or constraint params)
+  inputs?: InputParameter[];
+
+  // Variables to solve for
+  variables: ConstraintVariable[];
+
+  // Hard constraints that must all be satisfied
+  constraints: Constraint[];
+
+  // Soft constraints that influence solution ranking (optional)
+  preferences?: Preference[];
+
+  config?: Partial<ConstraintConfig>;
+};
+
+/**
+ * Constraint engine configuration.
+ *
+ * Controls how the engine searches for solutions. The defaults work well for
+ * most problems, but you can tune these for better performance on specific
+ * problem shapes.
+ */
+export type ConstraintConfig = {
+  mode: 'constraint';
+
+  /**
+   * Search strategy:
+   * - 'backtrack': Try values, undo when stuck, try again. Simple but can be slow.
+   * - 'forward-check': After each choice, eliminate values that would definitely
+   *   fail later. Catches dead-ends earlier but adds overhead per assignment.
+   * - 'arc-consistency': Even more aggressive pruning. Best for heavily
+   *   constrained problems. (Future implementation)
+   */
+  strategy: 'backtrack' | 'forward-check' | 'arc-consistency';
+
+  /**
+   * Variable ordering heuristic - which blank to fill in next:
+   * - 'static': Fill in order of definition. Predictable but not optimal.
+   * - 'mrv': "Minimum Remaining Values" - pick the blank with fewest choices
+   *   left. If a blank only has one valid option, fill it now. Fails fast.
+   * - 'degree': Pick the variable involved in the most constraints.
+   *   Useful when all domains are the same size. (Future implementation)
+   */
+  variableOrdering: 'static' | 'mrv' | 'degree';
+
+  /**
+   * Value ordering heuristic - which value to try first:
+   * - 'static': Try values in array order.
+   * - 'lcv': "Least Constraining Value" - try values that rule out the fewest
+   *   options for other variables. Finds solutions faster but adds overhead.
+   *   (Future implementation)
+   */
+  valueOrdering: 'static' | 'lcv';
+
+  /**
+   * Max search iterations before giving up. Each iteration is one value
+   * assignment attempt. For N variables with D domain values each, worst
+   * case is D^N iterations. Default: 100,000.
+   */
+  maxIterations: number;
+
+  /**
+   * For solveAll(): stop after finding this many solutions. Sometimes you
+   * just need a few valid options, not all of them. Default: 100.
+   */
+  maxSolutions: number;
+
+  /**
+   * Timeout in milliseconds. Complex problems can take a long time—this
+   * prevents infinite waits. Default: 30,000 (30 seconds).
+   */
+  timeout: number;
+
+  /**
+   * Optimization mode for preferences:
+   * - 'none': Don't optimize, just find valid solutions (default, backwards compatible)
+   * - 'maximize': Find solutions with highest preference score
+   * - 'minimize': Find solutions with lowest preference score (for cost-like preferences)
+   *
+   * When set to 'maximize' or 'minimize', solutions are scored and ranked by
+   * their total preference score. Only relevant when preferences are defined.
+   */
+  optimize: 'none' | 'maximize' | 'minimize';
+};
+
+// ========================================
+// Compiled Types
+// ========================================
+
+/**
+ * Compiled constraint variable.
+ *
+ * The domain is copied to prevent mutation, and an index is added for
+ * fast array-based lookups during search.
+ */
+export type CompiledConstraintVariable = {
+  name: string;
+  domain: any[];
+  index: number;  // Position in variable array (for efficient lookup)
+};
+
+/**
+ * Compiled constraint.
+ *
+ * Variables are resolved to indices, and the rule condition is compiled
+ * to an optimized form for fast evaluation during search.
+ */
+export type CompiledConstraint = {
+  id: string;
+  name?: string;
+  variableIndices: number[];   // Indices of involved variables
+  variableNames: string[];     // Names for binding context
+  condition: CompiledCondition;
+};
+
+/**
+ * Compiled preference.
+ *
+ * Similar to CompiledConstraint but includes the numeric weight for scoring.
+ * Semantic weights are resolved to their numeric values at compile time.
+ */
+export type CompiledPreference = {
+  id: string;
+  name?: string;
+  variableIndices: number[];   // Indices of involved variables
+  variableNames: string[];     // Names for binding context
+  condition: CompiledCondition;
+  weight: number;              // Resolved numeric weight
+};
+
+/**
+ * Compiled constraint ruleset.
+ *
+ * Includes a precomputed "constraint graph" that maps each variable to
+ * the constraints it participates in. This allows the solver to quickly
+ * find which constraints to check after assigning a value.
+ */
+export type CompiledConstraintRuleSet = CompiledBaseRuleSet & {
+  mode: 'constraint';
+  inputs: CompiledInputParameter[];
+  variables: CompiledConstraintVariable[];
+  constraints: CompiledConstraint[];
+  preferences: CompiledPreference[];  // Compiled soft constraints
+  config: ConstraintConfig;
+
+  // Precomputed constraint graph for efficiency
+  // "When I assign variable 3, which constraints do I need to check?"
+  constraintsByVariable: Map<number, number[]>;  // variable index -> constraint indices
+};
+
+// ========================================
+// Runtime Types
+// ========================================
+
+/**
+ * Runtime options for constraint solving.
+ *
+ * Callbacks let you watch the search in real-time—useful for debugging
+ * or showing progress to users. Override limits can tighten or loosen
+ * constraints for specific solve calls.
+ */
+export type ConstraintOptions = {
+  /**
+   * Called each time the solver tries assigning a value to a variable.
+   * Useful for watching the search or logging attempts.
+   */
+  onAssign?: (variable: string, value: any) => void;
+
+  /**
+   * Called when the solver undoes an assignment because it led to a
+   * dead-end. Many backtracks usually means the problem is hard or
+   * the constraints are tight.
+   */
+  onBacktrack?: (variable: string) => void;
+
+  /**
+   * Called when a complete valid solution is found. For solveAll(),
+   * this is called for each solution discovered.
+   */
+  onSolution?: (assignment: Record<string, any>) => void;
+
+  /**
+   * Called periodically with search statistics. Useful for progress bars
+   * or deciding whether to abort a long search.
+   */
+  onProgress?: (stats: SearchStats) => void;
+
+  // Override config
+  maxIterations?: number;
+  maxSolutions?: number;
+  timeout?: number;
+};
+
+/**
+ * Search statistics.
+ *
+ * These metrics help you understand how hard the problem was and whether
+ * tuning might help:
+ * - High backtracks = tight constraints, consider forward-check strategy
+ * - High iterations but low backtracks = many valid paths, problem is easy
+ * - Hit iteration limit = problem may be too large, simplify or increase limit
+ */
+export type SearchStats = {
+  iterations: number;       // Total assignment attempts
+  backtracks: number;       // Times the solver had to undo and try again
+  pruned: number;           // Values eliminated early by forward checking
+  elapsed: number;          // Time in milliseconds
+};
+
+/**
+ * A single solution (variable assignments).
+ *
+ * Maps each variable name to its assigned value. For example:
+ * { monday_morning: 'Alice', monday_evening: 'Bob', tuesday_morning: 'Carol' }
+ */
+export type Assignment = Record<string, any>;
+
+/**
+ * Scored solution with preference details.
+ *
+ * When optimization is enabled, each solution includes its total score
+ * and which preferences were satisfied.
+ */
+export type ScoredSolution = {
+  assignment: Assignment;           // Variable -> value mapping
+  score: number;                    // Total preference score
+  satisfiedPreferences: string[];   // IDs of preferences that were satisfied
+};
+
+/**
+ * Result from solve() - finds one solution.
+ *
+ * If solved is true, assignment contains the valid variable->value mapping.
+ * If solved is false, check exhausted (no solution exists) or timedOut
+ * (gave up before finishing) to understand why.
+ *
+ * When optimize is 'maximize' or 'minimize', returns the best solution
+ * along with its score and satisfied preferences.
+ */
+export type ConstraintResult = {
+  solved: boolean;                  // Whether a solution was found
+  assignment?: Assignment;          // Variable -> value mapping
+  conflicts?: ConflictInfo[];       // If unsolved, which constraints couldn't be satisfied
+  stats: SearchStats;
+  exhausted: boolean;               // true if all possibilities checked (no solution exists)
+  timedOut: boolean;                // true if timeout reached (solution might exist)
+  executionTimeMs: number;          // Processing time in milliseconds
+
+  // Optimization results (when optimize != 'none')
+  score?: number;                   // Total preference score of the solution
+  satisfiedPreferences?: string[];  // IDs of preferences that were satisfied
+};
+
+/**
+ * Result from solveAll() - finds multiple solutions.
+ *
+ * solutions contains all valid assignments found (up to maxSolutions).
+ * complete=true means there are no more solutions—you have them all.
+ * complete=false means the search stopped early (hit limit or timeout).
+ *
+ * When optimize is 'maximize' or 'minimize', rankedSolutions contains
+ * solutions sorted by score (best first).
+ */
+export type ConstraintAllResult = {
+  solutions: Assignment[];          // All solutions found (unranked)
+  complete: boolean;                // true if search completed (no more solutions)
+  stats: SearchStats;
+  timedOut: boolean;
+  executionTimeMs: number;          // Processing time in milliseconds
+
+  // Optimization results (when optimize != 'none')
+  rankedSolutions?: ScoredSolution[]; // Solutions sorted by score (best first)
+};
+
+/**
+ * Information about a conflict.
+ *
+ * When solve() fails to find a solution, conflicts tell you which
+ * constraints were violated during the last attempted assignment.
+ * This helps diagnose over-constrained problems.
+ */
+export type ConflictInfo = {
+  constraintId: string;
+  constraintName?: string;
+  variables: string[];
+  values: Record<string, any>;      // The values that caused the conflict
+};