@higher.archi/boe 1.0.0

package/dist/engines/constraint/types.d.ts

@@ -0,0 +1,332 @@
+/**
+ * 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';
+/**
+ * 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;
+    domain: any[];
+    description?: string;
+};
+/**
+ * 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;
+    name?: string;
+    variables: string[];
+    rule: Condition;
+};
+/**
+ * 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' | 'very-important' | 'important' | 'nice-to-have' | 'slight' | 'tiebreaker';
+/**
+ * Mapping of semantic weights to numeric values.
+ */
+export declare const SEMANTIC_WEIGHTS: Record<SemanticWeight, number>;
+/**
+ * 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;
+    name?: string;
+    variables: string[];
+    rule: Condition;
+    weight: PreferenceWeight;
+};
+/**
+ * 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';
+    inputs?: InputParameter[];
+    variables: ConstraintVariable[];
+    constraints: Constraint[];
+    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 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;
+};
+/**
+ * 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[];
+    variableNames: string[];
+    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[];
+    variableNames: string[];
+    condition: CompiledCondition;
+    weight: number;
+};
+/**
+ * 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[];
+    config: ConstraintConfig;
+    constraintsByVariable: Map<number, number[]>;
+};
+/**
+ * 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;
+    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;
+    backtracks: number;
+    pruned: number;
+    elapsed: number;
+};
+/**
+ * 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;
+    score: number;
+    satisfiedPreferences: string[];
+};
+/**
+ * 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;
+    assignment?: Assignment;
+    conflicts?: ConflictInfo[];
+    stats: SearchStats;
+    exhausted: boolean;
+    timedOut: boolean;
+    executionTimeMs: number;
+    score?: number;
+    satisfiedPreferences?: string[];
+};
+/**
+ * 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[];
+    complete: boolean;
+    stats: SearchStats;
+    timedOut: boolean;
+    executionTimeMs: number;
+    rankedSolutions?: ScoredSolution[];
+};
+/**
+ * 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>;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/engines/constraint/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/engines/constraint/types.ts"],"names":[],"mappings":"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"}

package/dist/engines/constraint/types.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SEMANTIC_WEIGHTS = void 0;
+/**
+ * Mapping of semantic weights to numeric values.
+ */
+exports.SEMANTIC_WEIGHTS = {
+    'critical': 100,
+    'very-important': 50,
+    'important': 25,
+    'nice-to-have': 10,
+    'slight': 5,
+    'tiebreaker': 1
+};
+//# sourceMappingURL=types.js.map

package/dist/engines/constraint/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/engines/constraint/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;AAmEH;;GAEG;AACU,QAAA,gBAAgB,GAAmC;IAC9D,UAAU,EAAE,GAAG;IACf,gBAAgB,EAAE,EAAE;IACpB,WAAW,EAAE,EAAE;IACf,cAAc,EAAE,EAAE;IAClB,QAAQ,EAAE,CAAC;IACX,YAAY,EAAE,CAAC;CAChB,CAAC"}

package/dist/engines/defeasible/compiler.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Defeasible Engine Compiler
+ *
+ * Compiles source defeasible rulesets into optimized form for execution.
+ */
+import { DefeasibleRuleSet, CompiledDefeasibleRuleSet } from './types';
+/**
+ * Compile a defeasible ruleset
+ *
+ * @example
+ * ```typescript
+ * const compiled = compileDefeasibleRuleSet({
+ *   id: 'birds',
+ *   mode: 'defeasible',
+ *   rules: [
+ *     {
+ *       id: 'birds-fly',
+ *       inputs: [{ name: 'x', type: 'Animal' }],
+ *       when: ['equals', '$x.class', 'bird'],
+ *       conclude: 'canFly'
+ *     },
+ *     {
+ *       id: 'penguins-dont-fly',
+ *       inputs: [{ name: 'x', type: 'Animal' }],
+ *       when: ['equals', '$x.species', 'penguin'],
+ *       conclude: { not: 'canFly' },
+ *       defeats: ['birds-fly']
+ *     }
+ *   ]
+ * });
+ * ```
+ */
+export declare function compileDefeasibleRuleSet(ruleSet: DefeasibleRuleSet): CompiledDefeasibleRuleSet;
+//# sourceMappingURL=compiler.d.ts.map

package/dist/engines/defeasible/compiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../../../src/engines/defeasible/compiler.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,OAAO,EACL,iBAAiB,EAEjB,yBAAyB,EAW1B,MAAM,SAAS,CAAC;AAoOjB;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,iBAAiB,GAAG,yBAAyB,CA0B9F"}

package/dist/engines/defeasible/compiler.js

@@ -0,0 +1,251 @@
+"use strict";
+/**
+ * Defeasible Engine Compiler
+ *
+ * Compiles source defeasible rulesets into optimized form for execution.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compileDefeasibleRuleSet = compileDefeasibleRuleSet;
+const core_1 = require("../../core");
+const types_1 = require("./types");
+// ========================================
+// Default Configuration
+// ========================================
+const DEFAULT_CONFIG = {
+    mode: 'defeasible',
+    aggregation: 'average',
+    threshold: 0.5,
+    conflictResolution: 'specificity',
+    maxIterations: 100
+};
+// ========================================
+// Helper Functions
+// ========================================
+/**
+ * Normalize credibility to number
+ */
+function normalizeCredibility(credibility) {
+    if (credibility === undefined) {
+        return 1.0;
+    }
+    if (typeof credibility === 'number') {
+        return Math.max(0, Math.min(1, credibility));
+    }
+    return types_1.SEMANTIC_CREDIBILITIES[credibility] ?? 1.0;
+}
+/**
+ * Normalize defeat target to CompiledDefeat
+ */
+function normalizeDefeat(target) {
+    if (typeof target === 'string') {
+        return { rule: target, strength: 1.0 };
+    }
+    const strength = typeof target.strength === 'number'
+        ? Math.max(0, Math.min(1, target.strength))
+        : types_1.SEMANTIC_DEFEAT_STRENGTHS[target.strength] ?? 1.0;
+    return { rule: target.rule, strength };
+}
+/**
+ * Compile a conclusion to normalized form
+ */
+function compileConclusion(conclude) {
+    if (conclude === undefined) {
+        return null;
+    }
+    if (typeof conclude === 'string') {
+        return { literal: conclude, positive: true };
+    }
+    return { literal: conclude.not, positive: false };
+}
+/**
+ * Count condition nodes for complexity
+ */
+function countConditions(condition) {
+    if (!condition)
+        return 0;
+    if (condition.children) {
+        return 1 + condition.children.reduce((sum, c) => sum + countConditions(c), 0);
+    }
+    return 1;
+}
+/**
+ * Calculate rule complexity for prioritization
+ */
+function calculateComplexity(inputs, when) {
+    let score = 0;
+    score += inputs.length * 10;
+    score += countConditions(when) * 5;
+    for (const input of inputs) {
+        score += countConditions(input.where) * 2;
+    }
+    return score;
+}
+/**
+ * Compile path reference
+ */
+function compilePath(from) {
+    const str = from.startsWith('$') ? from.slice(1) : from;
+    const parts = str.split('.');
+    return {
+        param: parts[0],
+        path: parts.slice(1)
+    };
+}
+/**
+ * Compile an input parameter
+ */
+function compileInputParameter(input) {
+    const compiled = {
+        name: input.name,
+        type: input.type,
+        schema: input.shape ? (0, core_1.normalizeShape)(input.shape) : { type: 'object' }
+    };
+    if (input.where) {
+        compiled.where = (0, core_1.compileCondition)(input.where);
+    }
+    if (input.from) {
+        compiled.from = compilePath(input.from);
+    }
+    return compiled;
+}
+/**
+ * Count the number of conditions in a rule for specificity
+ */
+function countSpecificity(rule) {
+    let count = 0;
+    // Count input constraints (where clauses)
+    if (rule.inputs) {
+        for (const input of rule.inputs) {
+            if (input.where) {
+                count += countConditionNodes(input.where);
+            }
+        }
+    }
+    // Count when clause conditions
+    if (rule.when) {
+        count += countConditionNodes(rule.when);
+    }
+    return count;
+}
+/**
+ * Recursively count condition nodes for specificity
+ */
+function countConditionNodes(condition) {
+    if (!Array.isArray(condition)) {
+        return 0;
+    }
+    const op = condition[0];
+    // Logical operators contain nested conditions
+    if (op === 'and' || op === 'or') {
+        let count = 0;
+        for (let i = 1; i < condition.length; i++) {
+            count += countConditionNodes(condition[i]);
+        }
+        return count;
+    }
+    if (op === 'not') {
+        return countConditionNodes(condition[1]);
+    }
+    // Any other operator is one condition
+    return 1;
+}
+/**
+ * Compile a single defeasible rule
+ */
+function compileRule(rule, index) {
+    const inputs = (rule.inputs || []).map(compileInputParameter);
+    const when = rule.when ? (0, core_1.compileCondition)(rule.when) : undefined;
+    return {
+        id: rule.id,
+        name: rule.name,
+        salience: rule.salience ?? 0,
+        complexity: calculateComplexity(inputs, when),
+        index,
+        inputs,
+        when,
+        strength: rule.strength || 'defeasible',
+        credibility: normalizeCredibility(rule.credibility),
+        conclusion: compileConclusion(rule.conclude),
+        defeats: (rule.defeats || []).map(normalizeDefeat),
+        specificity: countSpecificity(rule)
+    };
+}
+/**
+ * Build superiority map from relations and explicit defeats
+ */
+function buildSuperiorityMap(rules, relations = []) {
+    const map = new Map();
+    // Add explicit superiority relations
+    for (const { superior, inferior } of relations) {
+        if (!map.has(inferior)) {
+            map.set(inferior, new Set());
+        }
+        map.get(inferior).add(superior);
+    }
+    // Add defeats from rules (for binary defeats, add to superiority)
+    for (const rule of rules) {
+        for (const defeat of rule.defeats) {
+            // Only add full-strength defeats to superiority map
+            if (defeat.strength >= 1.0) {
+                if (!map.has(defeat.rule)) {
+                    map.set(defeat.rule, new Set());
+                }
+                map.get(defeat.rule).add(rule.id);
+            }
+        }
+    }
+    return map;
+}
+// ========================================
+// Main Compiler
+// ========================================
+/**
+ * Compile a defeasible ruleset
+ *
+ * @example
+ * ```typescript
+ * const compiled = compileDefeasibleRuleSet({
+ *   id: 'birds',
+ *   mode: 'defeasible',
+ *   rules: [
+ *     {
+ *       id: 'birds-fly',
+ *       inputs: [{ name: 'x', type: 'Animal' }],
+ *       when: ['equals', '$x.class', 'bird'],
+ *       conclude: 'canFly'
+ *     },
+ *     {
+ *       id: 'penguins-dont-fly',
+ *       inputs: [{ name: 'x', type: 'Animal' }],
+ *       when: ['equals', '$x.species', 'penguin'],
+ *       conclude: { not: 'canFly' },
+ *       defeats: ['birds-fly']
+ *     }
+ *   ]
+ * });
+ * ```
+ */
+function compileDefeasibleRuleSet(ruleSet) {
+    // Merge config with defaults
+    const config = {
+        ...DEFAULT_CONFIG,
+        ...ruleSet.config
+    };
+    // Compile top-level inputs
+    const inputs = (ruleSet.inputs || []).map(compileInputParameter);
+    // Compile rules
+    const rules = ruleSet.rules.map((rule, index) => compileRule(rule, index));
+    // Build superiority map
+    const superiority = buildSuperiorityMap(rules, ruleSet.superiority);
+    return {
+        id: ruleSet.id,
+        name: ruleSet.name,
+        mode: 'defeasible',
+        schema: ruleSet.shape ? (0, core_1.normalizeShape)(ruleSet.shape) : { type: 'object' },
+        inputs,
+        rules,
+        superiority,
+        config
+    };
+}
+//# sourceMappingURL=compiler.js.map

package/dist/engines/defeasible/compiler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compiler.js","sourceRoot":"","sources":["../../../src/engines/defeasible/compiler.ts"],"names":[],"mappings":"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"}