@higher.archi/boe 1.0.0

package/src/engines/backward/strategy.ts

@@ -0,0 +1,229 @@
+/**
+ * Backward Chaining Engine Strategy
+ *
+ * Goal-driven reasoning with nested sub-goals.
+ *
+ * Given a goal to prove, finds rules that can prove it and checks
+ * if their conditions are satisfied by facts in working memory.
+ *
+ * Algorithm:
+ * 1. Find all rules that can prove the goal (action.prove === goal)
+ * 2. For each rule:
+ *    a. First, recursively prove any sub-goals (action.requires)
+ *    b. Then, try to match the rule's conditions against facts
+ * 3. If all sub-goals proven AND conditions match, the goal is proven
+ * 4. If no rules succeed, the goal cannot be proven
+ *
+ * Supports:
+ * - Multiple rules proving the same goal (tries each until one succeeds) = OR
+ * - Sub-goals via 'requires' field (all must be proven) = AND
+ * - Depth limiting to prevent infinite recursion
+ * - Proof tree generation for explainability
+ */
+
+import {
+  match,
+  BindingContext
+} from '../../core';
+import { IWorkingMemory } from '../../core/memory';
+
+import {
+  CompiledBackwardRuleSet,
+  CompiledBackwardRule,
+  CompiledBackwardAction,
+  BackwardOptions,
+  BackwardResult,
+  ProofStep,
+  ProofResult
+} from './types';
+
+export class BackwardChainingStrategy {
+  run(
+    ruleSet: CompiledBackwardRuleSet,
+    wm: IWorkingMemory,
+    options: BackwardOptions
+  ): BackwardResult {
+    const startTime = performance.now();
+    const { goal, onProve, maxDepth: maxDepthOverride } = options;
+
+    // Read config from ruleset, allow runtime override
+    const config = ruleSet.config;
+    const maxDepth = maxDepthOverride ?? config.maxDepth;
+
+    // Build a map of goal -> rules for efficient lookup
+    const goalToRules = this.buildGoalIndex(ruleSet.rules);
+
+    // Track stats
+    const firedRules: string[] = [];
+
+    // Attempt to prove the goal
+    const result = this.prove(
+      goal,
+      goalToRules,
+      wm,
+      0,
+      maxDepth,
+      firedRules,
+      onProve
+    );
+
+    const executionTimeMs = Math.round((performance.now() - startTime) * 100) / 100;
+
+    return {
+      iterations: result.rulesEvaluated,
+      fired: firedRules,
+      proven: result.proven,
+      goal: result.goal,
+      bindings: result.bindings,
+      proof: result.proof,
+      depth: result.depth,
+      executionTimeMs
+    };
+  }
+
+  /**
+   * Build an index mapping goals to the rules that can prove them
+   */
+  private buildGoalIndex(rules: CompiledBackwardRule[]): Map<string, CompiledBackwardRule[]> {
+    const index = new Map<string, CompiledBackwardRule[]>();
+
+    for (const rule of rules) {
+      const action = rule.action as CompiledBackwardAction;
+      const goal = action.prove;
+
+      if (!index.has(goal)) {
+        index.set(goal, []);
+      }
+      index.get(goal)!.push(rule);
+    }
+
+    return index;
+  }
+
+  /**
+   * Attempt to prove a goal using the available rules
+   */
+  private prove(
+    goal: string,
+    goalToRules: Map<string, CompiledBackwardRule[]>,
+    wm: IWorkingMemory,
+    depth: number,
+    maxDepth: number,
+    firedRules: string[],
+    onProve?: (ruleId: string, goal: string, bindings: BindingContext) => void
+  ): ProofResult {
+    // Check depth limit
+    if (depth >= maxDepth) {
+      return {
+        proven: false,
+        goal,
+        bindings: null,
+        proof: null,
+        depth,
+        rulesEvaluated: 0
+      };
+    }
+
+    // Find rules that can prove this goal
+    const rules = goalToRules.get(goal);
+    if (!rules || rules.length === 0) {
+      return {
+        proven: false,
+        goal,
+        bindings: null,
+        proof: null,
+        depth,
+        rulesEvaluated: 0
+      };
+    }
+
+    let totalRulesEvaluated = 0;
+    let maxDepthReached = depth;
+
+    // Try each rule that can prove this goal (OR - first success wins)
+    for (const rule of rules) {
+      totalRulesEvaluated++;
+
+      const action = rule.action as CompiledBackwardAction;
+      const requires = action.requires;
+
+      // Step 1: Prove all sub-goals first (AND - all must succeed)
+      const subProofs: ProofStep[] = [];
+      let allSubGoalsProven = true;
+
+      for (const subGoal of requires) {
+        const subResult = this.prove(
+          subGoal,
+          goalToRules,
+          wm,
+          depth + 1,
+          maxDepth,
+          firedRules,
+          onProve
+        );
+
+        totalRulesEvaluated += subResult.rulesEvaluated;
+        maxDepthReached = Math.max(maxDepthReached, subResult.depth);
+
+        if (!subResult.proven) {
+          // Sub-goal failed - this rule path fails
+          allSubGoalsProven = false;
+          break;
+        }
+
+        // Sub-goal succeeded - add to proof tree
+        if (subResult.proof) {
+          subProofs.push(subResult.proof);
+        }
+      }
+
+      // If any sub-goal failed, try the next rule
+      if (!allSubGoalsProven) {
+        continue;
+      }
+
+      // Step 2: All sub-goals proven (or none required), now check conditions
+      const activations = match(rule, wm);
+
+      if (activations.length > 0) {
+        // Use the first activation (could add conflict resolution later)
+        const activation = activations[0];
+
+        // Rule succeeded!
+        firedRules.push(rule.id);
+        onProve?.(rule.id, goal, activation.facts);
+
+        const proofStep: ProofStep = {
+          ruleId: rule.id,
+          goal,
+          bindings: activation.facts,
+          subProofs  // Include nested sub-goal proofs
+        };
+
+        return {
+          proven: true,
+          goal,
+          bindings: activation.facts,
+          proof: proofStep,
+          depth: Math.max(depth + 1, maxDepthReached),
+          rulesEvaluated: totalRulesEvaluated
+        };
+      }
+
+      maxDepthReached = Math.max(maxDepthReached, depth + 1);
+    }
+
+    // No rules matched - goal cannot be proven
+    return {
+      proven: false,
+      goal,
+      bindings: null,
+      proof: null,
+      depth: maxDepthReached,
+      rulesEvaluated: totalRulesEvaluated
+    };
+  }
+}
+
+// Export a singleton instance for convenience
+export const backwardStrategy = new BackwardChainingStrategy();

package/src/engines/backward/types.ts

@@ -0,0 +1,125 @@
+/**
+ * Backward Chaining Engine Types
+ */
+
+import {
+  BaseRule,
+  BaseRuleSet,
+  CompiledBaseRule,
+  CompiledBaseRuleSet,
+  BindingContext
+} from '../../core';
+
+// ========================================
+// Source Types (User-Defined)
+// ========================================
+
+/**
+ * Backward chaining rule - uses 'prove' for goals
+ *
+ * Supports nested goals via 'requires' field (AND logic):
+ *   requires: ['goal-a', 'goal-b']  // All must be proven first
+ *
+ * OR logic is achieved by having multiple rules prove the same goal:
+ *   { prove: 'is-valid', where: [...condition A...] }
+ *   { prove: 'is-valid', where: [...condition B...] }  // Either rule can prove it
+ */
+export type BackwardRule = BaseRule & {
+  prove: string;
+  requires?: string[];  // Sub-goals that must be proven first (AND logic)
+};
+
+/**
+ * Backward chaining ruleset
+ */
+export type BackwardRuleSet = BaseRuleSet & {
+  mode: 'backward';
+  rules: BackwardRule[];
+  config?: Partial<BackwardConfig>;
+};
+
+/**
+ * Backward chaining configuration
+ */
+export type BackwardConfig = {
+  mode: 'backward';
+  maxDepth: number;
+};
+
+// ========================================
+// Compiled Types
+// ========================================
+
+/**
+ * Compiled backward chaining action
+ */
+export type CompiledBackwardAction = {
+  mode: 'backward';
+  prove: string;
+  requires: string[];  // Sub-goals to prove first (empty array if none)
+};
+
+/**
+ * Compiled backward chaining rule
+ */
+export type CompiledBackwardRule = CompiledBaseRule & {
+  action: CompiledBackwardAction;
+};
+
+/**
+ * Compiled backward chaining ruleset
+ */
+export type CompiledBackwardRuleSet = CompiledBaseRuleSet & {
+  mode: 'backward';
+  rules: CompiledBackwardRule[];
+  config: BackwardConfig;
+};
+
+// ========================================
+// Runtime Types
+// ========================================
+
+/**
+ * A proof step represents one rule that was used in proving a goal
+ */
+export type ProofStep = {
+  ruleId: string;
+  goal: string;
+  bindings: BindingContext;
+  subProofs: ProofStep[];  // Sub-goals that were proven to satisfy this rule
+};
+
+/**
+ * Result of a backward chaining proof attempt
+ */
+export type ProofResult = {
+  proven: boolean;
+  goal: string;
+  bindings: BindingContext | null;  // Variable bindings if proven
+  proof: ProofStep | null;          // Proof tree if proven
+  depth: number;                    // Max depth reached
+  rulesEvaluated: number;           // Number of rules checked
+};
+
+/**
+ * Runtime options for backward chaining execution
+ */
+export type BackwardOptions = {
+  goal: string;                    // The goal to prove
+  onProve?: (ruleId: string, goal: string, bindings: BindingContext) => void;
+  maxDepth?: number;               // Optional override of ruleset config
+};
+
+/**
+ * Result from backward chaining strategy execution
+ */
+export type BackwardResult = {
+  iterations: number;              // Kept for consistency with other strategies
+  fired: string[];                 // Rules that contributed to the proof
+  proven: boolean;                 // Whether the goal was proven
+  goal: string;                    // The goal that was attempted
+  bindings: BindingContext | null; // Variable bindings if proven
+  proof: ProofStep | null;         // Full proof tree if proven
+  depth: number;                   // Max depth reached during proving
+  executionTimeMs: number;         // Processing time in milliseconds
+};