@higher.archi/boe 1.0.0

package/src/engines/forward/engine.ts

@@ -0,0 +1,138 @@
+/**
+ * Forward Chaining Engine
+ *
+ * Self-contained engine for forward chaining rule execution.
+ * Implements IRuleEngine with strongly-typed ruleset, options, and result.
+ */
+
+import {
+  IRuleEngine,
+  WorkingMemory,
+  Fact,
+  FactInput,
+  FactChange
+} from '../../core';
+
+import {
+  CompiledForwardRuleSet,
+  ForwardOptions,
+  ForwardResult
+} from './types';
+
+import { ForwardChainingStrategy } from './strategy';
+
+/**
+ * Forward chaining rule engine.
+ *
+ * Executes rules in a data-driven manner, repeatedly matching rules against
+ * working memory and firing the highest-priority match until no more rules apply.
+ *
+ * @example
+ * ```typescript
+ * const engine = new ForwardEngine();
+ * engine.add({ type: 'Order', data: { amount: 100, status: 'pending' } });
+ *
+ * const result = engine.execute(compiledRules, {
+ *   actions: { processOrder: (ctx, wm) => { ... } }
+ * });
+ * ```
+ *
+ * @example Shared WorkingMemory
+ * ```typescript
+ * const wm = new WorkingMemory();
+ * const engine = new ForwardEngine(wm);
+ * ```
+ */
+export class ForwardEngine implements IRuleEngine<CompiledForwardRuleSet, ForwardOptions, ForwardResult> {
+  private wm: WorkingMemory;
+  private strategy: ForwardChainingStrategy;
+
+  /**
+   * Create a new ForwardEngine.
+   *
+   * @param workingMemory - Optional shared WorkingMemory. If not provided, creates its own.
+   */
+  constructor(workingMemory?: WorkingMemory) {
+    this.wm = workingMemory ?? new WorkingMemory();
+    this.strategy = new ForwardChainingStrategy();
+  }
+
+  // ========================================
+  // 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 forward chaining ruleset.
+   *
+   * Rules are matched against working memory iteratively. On each iteration,
+   * the highest-priority matching rule fires, potentially modifying working memory.
+   * Execution continues until no rules match or maxIterations is reached.
+   *
+   * @param ruleSet - Compiled forward ruleset
+   * @param options - Runtime options (actions, callbacks, iteration limit)
+   * @returns Execution result with fired rules and iteration count
+   */
+  execute(ruleSet: CompiledForwardRuleSet, options: ForwardOptions = {}): ForwardResult {
+    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/forward/index.ts

@@ -0,0 +1,51 @@
+/**
+ * Forward Chaining Engine
+ *
+ * Provides forward chaining (data-driven) rule execution.
+ * Rules fire when their conditions match facts in working memory,
+ * and continue firing until no more rules match.
+ */
+
+// Types
+export {
+  // Source types
+  SetAction,
+  RetractAction,
+  CallAction,
+  HaltAction,
+  ActionItem,
+  ThenValue,
+  ForwardRule,
+  ForwardRuleSet,
+  ForwardConfig,
+  // Compiled types
+  CompiledSetAction,
+  CompiledRetractAction,
+  CompiledCallAction,
+  CompiledHaltAction,
+  CompiledActionItem,
+  CompiledForwardAction,
+  CompiledForwardRule,
+  CompiledForwardRuleSet,
+  // Runtime types
+  ActionResult,
+  ActionHandler,
+  ActionRegistry,
+  ForwardOptions,
+  ForwardResult
+} from './types';
+
+// Compiler
+export {
+  compileForwardRule,
+  compileForwardRuleSet
+} from './compiler';
+
+// Strategy
+export {
+  ForwardChainingStrategy,
+  forwardStrategy
+} from './strategy';
+
+// Engine
+export { ForwardEngine } from './engine';

package/src/engines/forward/strategy.ts

@@ -0,0 +1,197 @@
+/**
+ * Forward Chaining Engine Strategy
+ */
+
+import {
+  match,
+  resolveConflicts,
+  Refraction,
+  resolveOperand,
+  setValueAtPath,
+  evaluateExpression,
+  BindingContext
+} from '../../core';
+import { IWorkingMemory } from '../../core/memory';
+
+import {
+  CompiledForwardRuleSet,
+  CompiledForwardAction,
+  CompiledActionItem,
+  ForwardOptions,
+  ForwardResult,
+  ActionRegistry
+} from './types';
+
+export class ForwardChainingStrategy {
+  run(
+    ruleSet: CompiledForwardRuleSet,
+    wm: IWorkingMemory,
+    options: ForwardOptions = {}
+  ): ForwardResult {
+    const startTime = performance.now();
+    const {
+      actions = {},
+      onFire,
+      maxIterations: maxIterationsOverride
+    } = options;
+
+    // Read config from ruleset, allow runtime override
+    const config = ruleSet.config;
+    const maxIterations = maxIterationsOverride ?? config.maxIterations;
+    const strategies = config.strategies;
+
+    const refraction = new Refraction();
+    const fired: string[] = [];
+    let iterations = 0;
+    let halted = false;
+
+    while (iterations < maxIterations) {
+      const activations = ruleSet.rules.flatMap(rule => match(rule, wm));
+      const unfired = refraction.filter(activations);
+
+      if (unfired.length === 0) break;
+
+      const sorted = resolveConflicts(unfired, { strategies });
+      const top = sorted[0];
+
+      onFire?.(top.rule.id, top.facts);
+      refraction.markFired(top);
+      fired.push(top.rule.id);
+
+      // Execute action items in order
+      const ruleAction = top.rule.action as CompiledForwardAction;
+      const shouldHalt = this.executeActionItems(
+        ruleAction.actions,
+        top.facts,
+        wm,
+        actions,
+        refraction,
+        top.rule.id
+      );
+
+      if (shouldHalt) {
+        halted = true;
+        break;
+      }
+
+      iterations++;
+    }
+
+    const executionTimeMs = Math.round((performance.now() - startTime) * 100) / 100;
+
+    return {
+      iterations,
+      fired,
+      halted,
+      executionTimeMs
+    };
+  }
+
+  /**
+   * Execute a list of action items in order
+   * Returns true if execution should halt
+   */
+  private executeActionItems(
+    items: CompiledActionItem[],
+    context: BindingContext,
+    wm: IWorkingMemory,
+    actions: ActionRegistry,
+    refraction: Refraction,
+    currentRuleId: string
+  ): boolean {
+    for (const item of items) {
+      // Set action: modify properties on matched facts
+      if ('set' in item) {
+        for (const { target, value, expr } of item.set) {
+          const fact = context[target.param];
+          if (!fact) {
+            throw new Error(`Cannot set property on unknown fact: ${target.param}`);
+          }
+
+          // Resolve the value (could be constant, property ref, or expression)
+          let resolvedValue: any;
+          if (expr) {
+            // Value is a compiled expression - evaluate it
+            resolvedValue = evaluateExpression(expr, context);
+          } else if (value.type === 'constant') {
+            resolvedValue = value.value;
+          } else if (value.type === 'property') {
+            resolvedValue = resolveOperand(value, context);
+          } else {
+            // Function operand - not yet supported
+            throw new Error('Function operands in set actions are not yet supported');
+          }
+
+          // Set the value at the target path (auto-creates intermediate objects)
+          setValueAtPath(fact.data, target.path, resolvedValue);
+
+          // Update the fact in working memory
+          // Exclude current rule from refraction clearing to prevent infinite loops
+          // when a rule modifies a fact it matched on
+          refraction.retractByFactIdExcludingRule(fact.id, currentRuleId);
+          wm.update(fact);
+        }
+        continue;
+      }
+
+      // Retract action: remove fact from working memory
+      if ('retract' in item) {
+        const fact = context[item.retract];
+        if (!fact) {
+          throw new Error(`Cannot retract unknown fact: ${item.retract}`);
+        }
+        refraction.retractByFactId(fact.id);
+        wm.remove(fact.id);
+        continue;
+      }
+
+      // Call action: call registered action handler
+      if ('call' in item) {
+        const handler = actions[item.call];
+        if (!handler) {
+          throw new Error(`Action handler not found: ${item.call}`);
+        }
+
+        const result = handler(context, wm);
+
+        if (result) {
+          if (result.add) {
+            for (const fact of result.add) {
+              wm.add(fact);
+            }
+          }
+
+          if (result.remove) {
+            for (const factId of result.remove) {
+              refraction.retractByFactId(factId);
+              wm.remove(factId);
+            }
+          }
+
+          if (result.update) {
+            for (const fact of result.update) {
+              // Exclude current rule from refraction clearing to prevent infinite loops
+              refraction.retractByFactIdExcludingRule(fact.id, currentRuleId);
+              wm.update(fact);
+            }
+          }
+
+          if (result.halt) {
+            return true;  // Signal to halt
+          }
+        }
+        continue;
+      }
+
+      // Halt action: stop execution
+      if ('halt' in item) {
+        return true;  // Signal to halt
+      }
+    }
+
+    return false;  // Don't halt
+  }
+}
+
+// Export a singleton instance for convenience
+export const forwardStrategy = new ForwardChainingStrategy();

package/src/engines/forward/types.ts

@@ -0,0 +1,205 @@
+/**
+ * Forward Chaining Engine Types
+ */
+
+import {
+  BaseRule,
+  BaseRuleSet,
+  Operand,
+  CompiledBaseRule,
+  CompiledBaseRuleSet,
+  CompiledCondition,
+  CompiledPath,
+  CompiledOperand,
+  Fact,
+  BindingContext,
+  ConflictStrategy
+} from '../../core';
+import { IWorkingMemory } from '../../core/memory';
+
+// ========================================
+// Source Types (User-Defined)
+// ========================================
+
+/**
+ * Set action - modify properties on matched facts
+ * Keys are property refs like '$person.status', values are constants or expressions
+ */
+export type SetAction = {
+  set: Record<string, Operand>;
+};
+
+/**
+ * Retract action - remove a matched fact from working memory
+ * Value is a property ref like '$duplicate'
+ */
+export type RetractAction = {
+  retract: string;
+};
+
+/**
+ * Call action - call a registered action handler by name
+ */
+export type CallAction = {
+  call: string;
+};
+
+/**
+ * Halt action - stop rule engine execution
+ */
+export type HaltAction = {
+  halt: true;
+};
+
+/**
+ * Union of all action item types
+ */
+export type ActionItem = SetAction | RetractAction | CallAction | HaltAction;
+
+/**
+ * Flexible 'then' value:
+ * - string: shorthand for { call: 'handlerName' }
+ * - ActionItem: single action object
+ * - ActionItem[]: array of actions executed in order
+ */
+export type ThenValue = string | ActionItem | ActionItem[];
+
+/**
+ * Forward chaining rule - uses 'then' for actions
+ */
+export type ForwardRule = BaseRule & {
+  then: ThenValue;
+};
+
+/**
+ * Forward chaining ruleset
+ */
+export type ForwardRuleSet = BaseRuleSet & {
+  mode: 'forward';
+  rules: ForwardRule[];
+  config?: Partial<ForwardConfig>;
+};
+
+/**
+ * Forward chaining configuration
+ */
+export type ForwardConfig = {
+  mode: 'forward';
+  maxIterations: number;
+  strategies: ConflictStrategy[];
+};
+
+// ========================================
+// Compiled Types
+// ========================================
+
+/**
+ * Compiled set action - property paths and expressions are pre-compiled
+ */
+export type CompiledSetAction = {
+  set: Array<{
+    target: CompiledPath;      // Parsed target path: { param: 'person', path: ['status'] }
+    value: CompiledOperand;    // Constant or property reference
+    expr?: CompiledCondition;  // If value is an expression, it's compiled here
+  }>;
+};
+
+/**
+ * Compiled retract action - just the parameter name ($ stripped)
+ */
+export type CompiledRetractAction = {
+  retract: string;  // Parameter name without $
+};
+
+/**
+ * Compiled call action - unchanged from source
+ */
+export type CompiledCallAction = {
+  call: string;
+};
+
+/**
+ * Compiled halt action - unchanged from source
+ */
+export type CompiledHaltAction = {
+  halt: true;
+};
+
+/**
+ * Union of all compiled action item types
+ */
+export type CompiledActionItem =
+  | CompiledSetAction
+  | CompiledRetractAction
+  | CompiledCallAction
+  | CompiledHaltAction;
+
+/**
+ * Compiled forward chaining action - always normalized to array
+ */
+export type CompiledForwardAction = {
+  mode: 'forward';
+  actions: CompiledActionItem[];
+};
+
+/**
+ * Compiled forward chaining rule
+ */
+export type CompiledForwardRule = CompiledBaseRule & {
+  action: CompiledForwardAction;
+};
+
+/**
+ * Compiled forward chaining ruleset
+ */
+export type CompiledForwardRuleSet = CompiledBaseRuleSet & {
+  mode: 'forward';
+  rules: CompiledForwardRule[];
+  config: ForwardConfig;
+};
+
+// ========================================
+// Runtime Types
+// ========================================
+
+/**
+ * Action handler result - what actions can return
+ */
+export type ActionResult = {
+  add?: Fact[];
+  remove?: string[];
+  update?: Fact[];
+  halt?: boolean;
+};
+
+/**
+ * Action handler signature
+ */
+export type ActionHandler = (
+  context: BindingContext,
+  wm: IWorkingMemory
+) => ActionResult | void;
+
+/**
+ * Registry of action handlers
+ */
+export type ActionRegistry = Record<string, ActionHandler>;
+
+/**
+ * Runtime options for forward chaining execution
+ */
+export type ForwardOptions = {
+  actions?: ActionRegistry;
+  onFire?: (ruleId: string, context: BindingContext) => void;
+  maxIterations?: number;  // Optional override of ruleset config
+};
+
+/**
+ * Execution result
+ */
+export type ForwardResult = {
+  iterations: number;
+  fired: string[];
+  halted: boolean;
+  executionTimeMs: number;  // Processing time in milliseconds
+};