@higher.archi/boe 1.0.0

package/src/engines/defeasible/compiler.ts

@@ -0,0 +1,306 @@
+/**
+ * Defeasible Engine Compiler
+ *
+ * Compiles source defeasible rulesets into optimized form for execution.
+ */
+
+import {
+  compileCondition,
+  normalizeShape
+} from '../../core';
+
+import {
+  DefeasibleRuleSet,
+  DefeasibleRule,
+  CompiledDefeasibleRuleSet,
+  CompiledDefeasibleRule,
+  CompiledConclusion,
+  CompiledDefeat,
+  SuperiorityMap,
+  DefeasibleConfig,
+  DefeatTarget,
+  Credibility,
+  SEMANTIC_DEFEAT_STRENGTHS,
+  SEMANTIC_CREDIBILITIES,
+  SemanticDefeatStrength
+} from './types';
+
+// ========================================
+// Default Configuration
+// ========================================
+
+const DEFAULT_CONFIG: Required<DefeasibleConfig> = {
+  mode: 'defeasible',
+  aggregation: 'average',
+  threshold: 0.5,
+  conflictResolution: 'specificity',
+  maxIterations: 100
+};
+
+// ========================================
+// Helper Functions
+// ========================================
+
+/**
+ * Normalize credibility to number
+ */
+function normalizeCredibility(credibility: Credibility | undefined): number {
+  if (credibility === undefined) {
+    return 1.0;
+  }
+  if (typeof credibility === 'number') {
+    return Math.max(0, Math.min(1, credibility));
+  }
+  return SEMANTIC_CREDIBILITIES[credibility] ?? 1.0;
+}
+
+/**
+ * Normalize defeat target to CompiledDefeat
+ */
+function normalizeDefeat(target: DefeatTarget): CompiledDefeat {
+  if (typeof target === 'string') {
+    return { rule: target, strength: 1.0 };
+  }
+
+  const strength = typeof target.strength === 'number'
+    ? Math.max(0, Math.min(1, target.strength))
+    : SEMANTIC_DEFEAT_STRENGTHS[target.strength as SemanticDefeatStrength] ?? 1.0;
+
+  return { rule: target.rule, strength };
+}
+
+/**
+ * Compile a conclusion to normalized form
+ */
+function compileConclusion(conclude: string | { not: string } | undefined): CompiledConclusion | null {
+  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?: any): number {
+  if (!condition) return 0;
+  if (condition.children) {
+    return 1 + condition.children.reduce((sum: number, c: any) => sum + countConditions(c), 0);
+  }
+  return 1;
+}
+
+/**
+ * Calculate rule complexity for prioritization
+ */
+function calculateComplexity(inputs: any[], when?: any): number {
+  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: string) {
+  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: 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;
+}
+
+/**
+ * Count the number of conditions in a rule for specificity
+ */
+function countSpecificity(rule: DefeasibleRule): number {
+  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: any): number {
+  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: DefeasibleRule, index: number): CompiledDefeasibleRule {
+  const inputs = (rule.inputs || []).map(compileInputParameter);
+  const when = rule.when ? 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: CompiledDefeasibleRule[],
+  relations: { superior: string; inferior: string }[] = []
+): SuperiorityMap {
+  const map: SuperiorityMap = 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']
+ *     }
+ *   ]
+ * });
+ * ```
+ */
+export function compileDefeasibleRuleSet(ruleSet: DefeasibleRuleSet): CompiledDefeasibleRuleSet {
+  // Merge config with defaults
+  const config: Required<DefeasibleConfig> = {
+    ...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 ? normalizeShape(ruleSet.shape) : { type: 'object' },
+    inputs,
+    rules,
+    superiority,
+    config
+  };
+}

package/src/engines/defeasible/engine.ts

@@ -0,0 +1,142 @@
+/**
+ * Defeasible Engine
+ *
+ * Non-monotonic reasoning engine supporting rules that can be
+ * defeated (overridden) by other rules.
+ *
+ * @example
+ * ```typescript
+ * const engine = new DefeasibleEngine();
+ *
+ * engine.add({ type: 'Animal', data: { class: 'bird', species: 'penguin' } });
+ *
+ * const result = engine.execute(compiled, {
+ *   onDefeat: (defeated, by, conclusion) => {
+ *     console.log(`${defeated} defeated by ${by}`);
+ *   }
+ * });
+ *
+ * console.log(result.query('canFly'));
+ * // { holds: false, status: 'defeated', confidence: 0.2 }
+ * ```
+ */
+
+import {
+  IRuleEngine,
+  WorkingMemory,
+  Fact,
+  FactInput,
+  FactChange
+} from '../../core';
+
+import {
+  CompiledDefeasibleRuleSet,
+  DefeasibleOptions,
+  DefeasibleResult
+} from './types';
+
+import { DefeasibleStrategy } from './strategy';
+
+/**
+ * Defeasible reasoning engine.
+ *
+ * Evaluates rules that can be defeated by other rules, supporting:
+ * - Strict rules (cannot be defeated)
+ * - Defeasible rules (can be overridden)
+ * - Defeaters (block without asserting)
+ * - Weighted defeat strengths
+ * - Configurable aggregation strategies
+ */
+export class DefeasibleEngine implements IRuleEngine<CompiledDefeasibleRuleSet, DefeasibleOptions, DefeasibleResult> {
+  private wm: WorkingMemory;
+  private strategy: DefeasibleStrategy;
+
+  /**
+   * Create a new DefeasibleEngine.
+   *
+   * @param workingMemory - Optional shared WorkingMemory. If not provided, creates its own.
+   */
+  constructor(workingMemory?: WorkingMemory) {
+    this.wm = workingMemory ?? new WorkingMemory();
+    this.strategy = new DefeasibleStrategy();
+  }
+
+  // ========================================
+  // 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
+  // ========================================
+
+  /**
+   * Execute a defeasible ruleset.
+   *
+   * Matches rules against working memory, detects conflicts,
+   * applies defeat relationships, and computes final conclusions
+   * with confidence scores.
+   *
+   * @param ruleSet - Compiled defeasible ruleset
+   * @param options - Runtime options (callbacks, query filter)
+   * @returns Execution result with conclusions, conflicts, and query function
+   */
+  execute(ruleSet: CompiledDefeasibleRuleSet, options: DefeasibleOptions = {}): DefeasibleResult {
+    return this.strategy.run(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/defeasible/index.ts

@@ -0,0 +1,48 @@
+/**
+ * Defeasible Engine
+ *
+ * Non-monotonic reasoning engine supporting rules that can be
+ * defeated (overridden) by other rules.
+ */
+
+// Engine
+export { DefeasibleEngine } from './engine';
+
+// Compiler
+export { compileDefeasibleRuleSet } from './compiler';
+
+// Types
+export {
+  // Rule strength
+  RuleStrength,
+  ConclusionStatus,
+
+  // Defeat types
+  SemanticDefeatStrength,
+  SEMANTIC_DEFEAT_STRENGTHS,
+  DefeatTarget,
+  Credibility,
+  SEMANTIC_CREDIBILITIES,
+
+  // Source types
+  DefeasibleRule,
+  SuperiorityRelation,
+  AggregationStrategy,
+  DefeasibleConfig,
+  DefeasibleRuleSet,
+
+  // Compiled types
+  CompiledConclusion,
+  CompiledDefeat,
+  CompiledDefeasibleRule,
+  SuperiorityMap,
+  CompiledDefeasibleRuleSet,
+
+  // Runtime types
+  FiredRule,
+  Derivation,
+  Conflict,
+  DefeasibleOptions,
+  DefeasibleResult,
+  QueryResult
+} from './types';