@higher.archi/boe 1.0.0

package/src/engines/defeasible/strategy.ts

@@ -0,0 +1,573 @@
+/**
+ * Defeasible Engine Strategy
+ *
+ * Core algorithm for defeasible reasoning with weighted defeats.
+ * Implements fixed-point iteration to resolve conflicts and compute conclusions.
+ */
+
+import { match } from '../../core/matching';
+import { IWorkingMemory } from '../../core/memory';
+
+import {
+  CompiledDefeasibleRuleSet,
+  CompiledDefeasibleRule,
+  DefeasibleOptions,
+  DefeasibleResult,
+  FiredRule,
+  Derivation,
+  Conflict,
+  ConclusionStatus,
+  QueryResult,
+  AggregationStrategy
+} from './types';
+
+// ========================================
+// Aggregation Strategies
+// ========================================
+
+/**
+ * Calculate confidence using the specified aggregation strategy
+ */
+function aggregateConfidence(
+  strategy: AggregationStrategy,
+  supporters: { credibility: number }[],
+  attackers: { credibility: number; defeatStrength: number }[]
+): number {
+  if (supporters.length === 0) {
+    return 0;
+  }
+
+  const supportCredibilities = supporters.map(s => s.credibility);
+  const attackValues = attackers.map(a => a.credibility * a.defeatStrength);
+
+  switch (strategy) {
+    case 'average': {
+      const avgSupport = supportCredibilities.reduce((a, b) => a + b, 0) / supportCredibilities.length;
+      const avgAttack = attackValues.length > 0
+        ? attackValues.reduce((a, b) => a + b, 0) / attackValues.length
+        : 0;
+      return Math.max(0, Math.min(1, avgSupport - avgAttack));
+    }
+
+    case 'max-min': {
+      const maxSupport = Math.max(...supportCredibilities);
+      const maxAttack = attackValues.length > 0 ? Math.max(...attackValues) : 0;
+      return Math.max(0, Math.min(1, maxSupport - maxAttack));
+    }
+
+    case 'weighted-sum': {
+      const totalSupport = supportCredibilities.reduce((a, b) => a + b, 0);
+      const totalAttack = attackValues.reduce((a, b) => a + b, 0);
+      const total = totalSupport + totalAttack;
+      return total > 0 ? totalSupport / total : 0;
+    }
+
+    case 'probabilistic': {
+      // Probability that at least one supporter holds
+      let probSupport = 1;
+      for (const c of supportCredibilities) {
+        probSupport *= (1 - c);
+      }
+      probSupport = 1 - probSupport;
+
+      // Probability of being defeated
+      let probDefeat = 0;
+      for (const a of attackValues) {
+        probDefeat = probDefeat + a - (probDefeat * a);
+      }
+
+      return Math.max(0, Math.min(1, probSupport * (1 - probDefeat)));
+    }
+
+    default:
+      return supportCredibilities[0] || 0;
+  }
+}
+
+// ========================================
+// Strategy Implementation
+// ========================================
+
+export class DefeasibleStrategy {
+  run(
+    ruleSet: CompiledDefeasibleRuleSet,
+    wm: IWorkingMemory,
+    options: DefeasibleOptions = {}
+  ): DefeasibleResult {
+    const startTime = performance.now();
+    const { onFire, onDefeat, onConflict } = options;
+    const config = ruleSet.config;
+
+    // Phase 1: Match all rules and collect fired rules
+    const firedRules: FiredRule[] = [];
+    const firedRuleIds: string[] = [];
+
+    for (const rule of ruleSet.rules) {
+      // Match inputs against working memory (includes when clause evaluation)
+      const activations = match(rule, wm);
+
+      for (const activation of activations) {
+        // Rule fires
+        firedRules.push({
+          ruleId: rule.id,
+          conclusion: rule.conclusion,
+          credibility: rule.credibility,
+          bindings: activation.facts
+        });
+
+        if (!firedRuleIds.includes(rule.id)) {
+          firedRuleIds.push(rule.id);
+        }
+
+        if (onFire) {
+          onFire(rule.id, rule.conclusion, activation.facts);
+        }
+      }
+    }
+
+    // Phase 2: Group fired rules by conclusion
+    const conclusionSupport: Map<string, {
+      positive: FiredRule[];
+      negative: FiredRule[];
+    }> = new Map();
+
+    for (const fired of firedRules) {
+      if (!fired.conclusion) continue;
+
+      const literal = fired.conclusion.literal;
+      if (!conclusionSupport.has(literal)) {
+        conclusionSupport.set(literal, { positive: [], negative: [] });
+      }
+
+      const support = conclusionSupport.get(literal)!;
+      if (fired.conclusion.positive) {
+        support.positive.push(fired);
+      } else {
+        support.negative.push(fired);
+      }
+    }
+
+    // Phase 3: Build defeat relationships
+    const ruleMap = new Map<string, CompiledDefeasibleRule>();
+    for (const rule of ruleSet.rules) {
+      ruleMap.set(rule.id, rule);
+    }
+
+    // Track which rules defeat which
+    const defeatsMap: Map<string, { by: string; strength: number }[]> = new Map();
+
+    for (const fired of firedRules) {
+      const rule = ruleMap.get(fired.ruleId);
+      if (!rule) continue;
+
+      for (const defeat of rule.defeats) {
+        // Check if the defeated rule actually fired
+        if (firedRuleIds.includes(defeat.rule)) {
+          if (!defeatsMap.has(defeat.rule)) {
+            defeatsMap.set(defeat.rule, []);
+          }
+          defeatsMap.get(defeat.rule)!.push({
+            by: fired.ruleId,
+            strength: defeat.strength
+          });
+        }
+      }
+    }
+
+    // Phase 4: Resolve conflicts and compute conclusions
+    const conflicts: Conflict[] = [];
+    const derivations: Map<string, Derivation> = new Map();
+
+    for (const [literal, support] of conclusionSupport) {
+      const hasPositive = support.positive.length > 0;
+      const hasNegative = support.negative.length > 0;
+
+      // Check for conflict
+      if (hasPositive && hasNegative) {
+        const conflict = this.resolveConflict(
+          literal,
+          support.positive,
+          support.negative,
+          defeatsMap,
+          ruleMap,
+          config
+        );
+        conflicts.push(conflict);
+
+        if (onConflict) {
+          onConflict(conflict);
+        }
+
+        // Create derivations based on conflict resolution
+        if (conflict.winner === 'positive' || conflict.winner === 'undecided') {
+          this.addDerivation(derivations, literal, true, support.positive, defeatsMap, ruleMap, config, onDefeat);
+        }
+        if (conflict.winner === 'negative' || conflict.winner === 'undecided') {
+          this.addDerivation(derivations, literal, false, support.negative, defeatsMap, ruleMap, config, onDefeat);
+        }
+      } else {
+        // No conflict - just add the derivation
+        if (hasPositive) {
+          this.addDerivation(derivations, literal, true, support.positive, defeatsMap, ruleMap, config, onDefeat);
+        }
+        if (hasNegative) {
+          this.addDerivation(derivations, literal, false, support.negative, defeatsMap, ruleMap, config, onDefeat);
+        }
+      }
+    }
+
+    // Phase 5: Build result
+    const conclusions: Record<string, Derivation> = {};
+    const definitely: string[] = [];
+    const defeasibly: string[] = [];
+    const defeated: string[] = [];
+
+    for (const [key, derivation] of derivations) {
+      conclusions[key] = derivation;
+
+      if (derivation.status === 'definitely') {
+        definitely.push(derivation.conclusion);
+      } else if (derivation.status === 'defeasibly') {
+        defeasibly.push(derivation.conclusion);
+      } else if (derivation.status === 'defeated' || derivation.status === 'blocked') {
+        defeated.push(derivation.conclusion);
+      }
+    }
+
+    // Query function
+    const query = (conclusion: string): QueryResult => {
+      // Try positive
+      const posKey = `+${conclusion}`;
+      const negKey = `-${conclusion}`;
+
+      const posDerivation = derivations.get(posKey);
+      const negDerivation = derivations.get(negKey);
+
+      // Positive holds
+      if (posDerivation && posDerivation.holds) {
+        return {
+          conclusion,
+          holds: true,
+          confidence: posDerivation.confidence,
+          status: posDerivation.status,
+          supportedBy: posDerivation.supportingRules,
+          defeatedBy: posDerivation.defeatedBy
+        };
+      }
+
+      // Negative holds
+      if (negDerivation && negDerivation.holds) {
+        return {
+          conclusion,
+          holds: false,
+          confidence: negDerivation.confidence,
+          status: negDerivation.status,
+          supportedBy: negDerivation.supportingRules,
+          defeatedBy: negDerivation.defeatedBy
+        };
+      }
+
+      // Check defeated
+      if (posDerivation) {
+        return {
+          conclusion,
+          holds: false,
+          confidence: posDerivation.confidence,
+          status: posDerivation.status,
+          supportedBy: posDerivation.supportingRules,
+          defeatedBy: posDerivation.defeatedBy
+        };
+      }
+
+      // Undecided
+      return {
+        conclusion,
+        holds: false,
+        confidence: 0,
+        status: 'undecided',
+        supportedBy: [],
+        defeatedBy: []
+      };
+    };
+
+    const executionTimeMs = Math.round((performance.now() - startTime) * 100) / 100;
+
+    return {
+      conclusions,
+      definitely,
+      defeasibly,
+      defeated,
+      conflicts,
+      fired: firedRuleIds,
+      iterations: 1,  // Current implementation is single-pass
+      executionTimeMs,
+      query
+    };
+  }
+
+  /**
+   * Resolve a conflict between positive and negative conclusions
+   */
+  private resolveConflict(
+    literal: string,
+    positive: FiredRule[],
+    negative: FiredRule[],
+    defeatsMap: Map<string, { by: string; strength: number }[]>,
+    ruleMap: Map<string, CompiledDefeasibleRule>,
+    config: Required<import('./types').DefeasibleConfig>
+  ): Conflict {
+    const positiveRuleIds = positive.map(f => f.ruleId);
+    const negativeRuleIds = negative.map(f => f.ruleId);
+
+    // Check for strict rules
+    const positiveStrict = positive.some(f => {
+      const rule = ruleMap.get(f.ruleId);
+      return rule?.strength === 'strict';
+    });
+    const negativeStrict = negative.some(f => {
+      const rule = ruleMap.get(f.ruleId);
+      return rule?.strength === 'strict';
+    });
+
+    if (positiveStrict && !negativeStrict) {
+      return {
+        conclusion: literal,
+        positiveRules: positiveRuleIds,
+        negativeRules: negativeRuleIds,
+        winner: 'positive',
+        reason: 'Positive supported by strict rule'
+      };
+    }
+
+    if (negativeStrict && !positiveStrict) {
+      return {
+        conclusion: literal,
+        positiveRules: positiveRuleIds,
+        negativeRules: negativeRuleIds,
+        winner: 'negative',
+        reason: 'Negative supported by strict rule'
+      };
+    }
+
+    if (positiveStrict && negativeStrict) {
+      return {
+        conclusion: literal,
+        positiveRules: positiveRuleIds,
+        negativeRules: negativeRuleIds,
+        winner: 'undecided',
+        reason: 'Conflict between strict rules'
+      };
+    }
+
+    // Check explicit defeats
+    const positiveDefeated = positiveRuleIds.every(id => {
+      const defeats = defeatsMap.get(id) || [];
+      return defeats.some(d => negativeRuleIds.includes(d.by) && d.strength >= 1.0);
+    });
+
+    const negativeDefeated = negativeRuleIds.every(id => {
+      const defeats = defeatsMap.get(id) || [];
+      return defeats.some(d => positiveRuleIds.includes(d.by) && d.strength >= 1.0);
+    });
+
+    if (positiveDefeated && !negativeDefeated) {
+      return {
+        conclusion: literal,
+        positiveRules: positiveRuleIds,
+        negativeRules: negativeRuleIds,
+        winner: 'negative',
+        reason: 'Positive rules defeated by explicit defeats'
+      };
+    }
+
+    if (negativeDefeated && !positiveDefeated) {
+      return {
+        conclusion: literal,
+        positiveRules: positiveRuleIds,
+        negativeRules: negativeRuleIds,
+        winner: 'positive',
+        reason: 'Negative rules defeated by explicit defeats'
+      };
+    }
+
+    // Use conflict resolution strategy
+    if (config.conflictResolution === 'specificity') {
+      const maxPosSpecificity = Math.max(...positive.map(f => ruleMap.get(f.ruleId)?.specificity || 0));
+      const maxNegSpecificity = Math.max(...negative.map(f => ruleMap.get(f.ruleId)?.specificity || 0));
+
+      if (maxPosSpecificity > maxNegSpecificity) {
+        return {
+          conclusion: literal,
+          positiveRules: positiveRuleIds,
+          negativeRules: negativeRuleIds,
+          winner: 'positive',
+          reason: `Positive more specific (${maxPosSpecificity} vs ${maxNegSpecificity})`
+        };
+      }
+
+      if (maxNegSpecificity > maxPosSpecificity) {
+        return {
+          conclusion: literal,
+          positiveRules: positiveRuleIds,
+          negativeRules: negativeRuleIds,
+          winner: 'negative',
+          reason: `Negative more specific (${maxNegSpecificity} vs ${maxPosSpecificity})`
+        };
+      }
+    }
+
+    if (config.conflictResolution === 'priority') {
+      const maxPosSalience = Math.max(...positive.map(f => ruleMap.get(f.ruleId)?.salience || 0));
+      const maxNegSalience = Math.max(...negative.map(f => ruleMap.get(f.ruleId)?.salience || 0));
+
+      if (maxPosSalience > maxNegSalience) {
+        return {
+          conclusion: literal,
+          positiveRules: positiveRuleIds,
+          negativeRules: negativeRuleIds,
+          winner: 'positive',
+          reason: `Positive higher priority (${maxPosSalience} vs ${maxNegSalience})`
+        };
+      }
+
+      if (maxNegSalience > maxPosSalience) {
+        return {
+          conclusion: literal,
+          positiveRules: positiveRuleIds,
+          negativeRules: negativeRuleIds,
+          winner: 'negative',
+          reason: `Negative higher priority (${maxNegSalience} vs ${maxPosSalience})`
+        };
+      }
+    }
+
+    return {
+      conclusion: literal,
+      positiveRules: positiveRuleIds,
+      negativeRules: negativeRuleIds,
+      winner: 'undecided',
+      reason: 'No resolution found'
+    };
+  }
+
+  /**
+   * Check if a rule is fully defeated (all its defeats have strength >= 1.0)
+   */
+  private isRuleDefeated(
+    ruleId: string,
+    defeatsMap: Map<string, { by: string; strength: number }[]>,
+    visited: Set<string> = new Set()
+  ): boolean {
+    // Prevent infinite loops
+    if (visited.has(ruleId)) return false;
+    visited.add(ruleId);
+
+    const defeats = defeatsMap.get(ruleId) || [];
+    if (defeats.length === 0) return false;
+
+    // Check if any attacker fully defeats this rule AND is not itself defeated
+    for (const defeat of defeats) {
+      if (defeat.strength >= 1.0) {
+        // Check if the attacker is also defeated (defeat chain)
+        const attackerDefeated = this.isRuleDefeated(defeat.by, defeatsMap, visited);
+        if (!attackerDefeated) {
+          return true; // Found an undefeated attacker with full strength
+        }
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Add a derivation for a conclusion
+   */
+  private addDerivation(
+    derivations: Map<string, Derivation>,
+    literal: string,
+    positive: boolean,
+    supporters: FiredRule[],
+    defeatsMap: Map<string, { by: string; strength: number }[]>,
+    ruleMap: Map<string, CompiledDefeasibleRule>,
+    config: Required<import('./types').DefeasibleConfig>,
+    onDefeat?: (defeated: string, by: string, conclusion: string) => void
+  ): void {
+    const key = positive ? `+${literal}` : `-${literal}`;
+    const conclusionName = positive ? literal : `not ${literal}`;
+
+    // Check if any supporting rule is strict
+    const hasStrict = supporters.some(f => {
+      const rule = ruleMap.get(f.ruleId);
+      return rule?.strength === 'strict';
+    });
+
+    // Collect attackers (rules that defeat our supporters)
+    // But filter out attackers that are themselves defeated
+    const attackers: { credibility: number; defeatStrength: number; ruleId: string }[] = [];
+    const defeatedBy: string[] = [];
+
+    for (const supporter of supporters) {
+      const defeats = defeatsMap.get(supporter.ruleId) || [];
+      for (const defeat of defeats) {
+        const attackerRule = ruleMap.get(defeat.by);
+        if (attackerRule) {
+          // Check if the attacker is itself defeated (defeat chain)
+          const attackerDefeated = this.isRuleDefeated(defeat.by, defeatsMap);
+
+          if (!attackerDefeated) {
+            attackers.push({
+              credibility: attackerRule.credibility,
+              defeatStrength: defeat.strength,
+              ruleId: defeat.by
+            });
+
+            if (!defeatedBy.includes(defeat.by)) {
+              defeatedBy.push(defeat.by);
+
+              if (onDefeat) {
+                onDefeat(supporter.ruleId, defeat.by, conclusionName);
+              }
+            }
+          }
+        }
+      }
+    }
+
+    // Calculate confidence
+    const confidence = hasStrict
+      ? 1.0
+      : aggregateConfidence(
+          config.aggregation,
+          supporters.map(s => ({ credibility: s.credibility })),
+          attackers
+        );
+
+    // Determine status
+    let status: ConclusionStatus;
+    const holds = confidence >= config.threshold;
+
+    if (hasStrict) {
+      status = 'definitely';
+    } else if (defeatedBy.length > 0 && !holds) {
+      status = 'defeated';
+    } else if (holds) {
+      status = 'defeasibly';
+    } else {
+      status = 'blocked';
+    }
+
+    derivations.set(key, {
+      conclusion: conclusionName,
+      positive,
+      holds,
+      confidence,
+      status,
+      supportingRules: supporters.map(s => s.ruleId),
+      defeatedBy,
+      bindings: supporters[0]?.bindings || {}
+    });
+  }
+}
+
+// Export singleton instance
+export const defeasibleStrategy = new DefeasibleStrategy();