@higher.archi/boe 1.0.0

package/src/core/types/condition.ts

@@ -0,0 +1,185 @@
+/**
+ * Core condition and operand types - shared across all engines
+ */
+
+// ========================================
+// Operator Type Definitions
+// ========================================
+
+export type UnaryOperator =
+  | 'isNaN' | 'isOdd' | 'isEven'
+  | 'isEmpty' | 'isNotEmpty'
+  | 'isTrue' | 'isFalse'
+  | 'isNull' | 'isNotNull' | 'isDefined' | 'isUndefined'
+  | 'not'
+  | 'abs' | 'negate' | 'sqrt' | 'ceil' | 'floor' | 'round'
+  | 'soundex' | 'nysiis' | 'caverphone2'
+  // String functions
+  | 'trim' | 'ltrim' | 'rtrim' | 'upper' | 'lower' | 'reverse' | 'length'
+  // Date generators (number → Date)
+  | 'secondsAgo' | 'minutesAgo' | 'hoursAgo' | 'daysAgo' | 'weeksAgo' | 'monthsAgo' | 'yearsAgo'
+  | 'secondsFromNow' | 'minutesFromNow' | 'hoursFromNow' | 'daysFromNow' | 'weeksFromNow' | 'monthsFromNow' | 'yearsFromNow'
+  // Date extraction (Date → number)
+  | 'getYear' | 'getMonth' | 'getDay' | 'getDayOfWeek' | 'getHour' | 'getMinute' | 'getSecond' | 'getQuarter' | 'getWeekOfYear'
+  // Date boundaries (Date → Date)
+  | 'startOfDay' | 'endOfDay' | 'startOfWeek' | 'endOfWeek' | 'startOfMonth' | 'endOfMonth' | 'startOfYear' | 'endOfYear'
+  // Date checks (Date → boolean)
+  | 'isWeekend' | 'isWeekday' | 'isLeapYear' | 'isFuture' | 'isPast' | 'isToday'
+  // Date constants (any → Date)
+  | 'now' | 'today' | 'tomorrow' | 'yesterday';
+
+export type BinaryOperator =
+  | 'equals' | 'notEquals'
+  | 'greaterThan' | 'greaterThanOrEquals'
+  | 'lessThan' | 'lessThanOrEquals'
+  | 'approximatelyEquals'
+  | 'contains' | 'startsWith' | 'endsWith'
+  | 'equalsIgnoreCase' | 'notEqualsIgnoreCase'
+  | 'startsWithIgnoreCase' | 'endsWithIgnoreCase'
+  | 'containsIgnoreCase'
+  | 'regex' | 'regexIgnoreCase'
+  | 'in'
+  | 'xor'
+  | 'add' | 'subtract' | 'multiply' | 'divide' | 'modulo' | 'power' | 'min' | 'max'
+  | 'soundexMatch' | 'nysiisMatch' | 'caverphone2Match'
+  | 'cosineSimilarity'
+  // String functions
+  | 'concat' | 'repeat'
+  // Date arithmetic (Date, number → Date)
+  | 'addSeconds' | 'addMinutes' | 'addHours' | 'addDays' | 'addWeeks' | 'addMonths' | 'addYears'
+  | 'subtractSeconds' | 'subtractMinutes' | 'subtractHours' | 'subtractDays' | 'subtractWeeks' | 'subtractMonths' | 'subtractYears'
+  // Date differences (Date, Date → number)
+  | 'diffMilliseconds' | 'diffSeconds' | 'diffMinutes' | 'diffHours' | 'diffDays' | 'diffWeeks' | 'diffMonths' | 'diffYears'
+  // Date comparisons (Date, Date → boolean)
+  | 'isBefore' | 'isAfter' | 'isSameDay' | 'isSameWeek' | 'isSameMonth' | 'isSameYear';
+
+export type TernaryOperator =
+  | 'substring' | 'replace' | 'replaceAll' | 'padStart' | 'padEnd'
+  // Date range (Date, Date, Date → boolean)
+  | 'isBetween';
+
+export type VariadicOperator = 'and' | 'or' | 'sum' | 'product' | 'average';
+
+export type Operator = UnaryOperator | BinaryOperator | TernaryOperator | VariadicOperator;
+
+// ========================================
+// Operand Types (source/uncompiled)
+// ========================================
+
+export type PropertyRef = `$${string}`;
+
+export type FunctionExpr = {
+  fn: string;
+  args: Operand[];
+};
+
+export type UnitValue = {
+  value: number;
+  unit: string;
+};
+
+export type ConstantValue =
+  | string
+  | number
+  | boolean
+  | null
+  | UnitValue
+  | any[];
+
+export type Operand =
+  | PropertyRef
+  | FunctionExpr
+  | ConstantValue;
+
+// ========================================
+// Condition Types (source/uncompiled)
+// ========================================
+
+export type UnaryCondition = [UnaryOperator, Operand];
+
+export type BinaryCondition = [BinaryOperator, Operand, Operand];
+
+export type TernaryCondition = [TernaryOperator, Operand, Operand, Operand];
+
+/**
+ * Variadic comparison conditions
+ * equals: ['equals', x, a, b, c] → x == a OR x == b OR x == c
+ * notEquals: ['notEquals', x, a, b, c] → x != a AND x != b AND x != c
+ */
+export type VariadicComparisonCondition =
+  | ['equals', Operand, Operand, Operand, ...Operand[]]
+  | ['notEquals', Operand, Operand, Operand, ...Operand[]];
+
+export type LogicalCondition =
+  | ["not", Condition]
+  | ["xor", Condition, Condition]
+  | ["and", ...Condition[]]
+  | ["or", ...Condition[]];
+
+/**
+ * Fuzzy membership conditions
+ * Used in fuzzy mode to check membership degree
+ *
+ * ['is', '$temp', 'temperature.hot']     -> membership degree (0-1)
+ * ['isNot', '$temp', 'temperature.hot']  -> 1 - membership degree
+ */
+export type FuzzyCondition =
+  | ["is", Operand, string]      // ['is', value, 'variable.term']
+  | ["isNot", Operand, string];  // ['isNot', value, 'variable.term']
+
+/**
+ * Expression string condition - allows inline expression syntax
+ *
+ * Examples:
+ * - ['expr', '$age >= 18 and $hasLicense == true']
+ * - ['expr', '$score > 90 or $bonus == true']
+ * - ['expr', '$price * $quantity > 100']
+ *
+ * Expression strings are parsed at compile time into the same
+ * internal representation as S-expression conditions.
+ */
+export type ExpressionTuple = ["expr", string];
+
+export type Condition =
+  | UnaryCondition
+  | BinaryCondition
+  | TernaryCondition
+  | VariadicComparisonCondition
+  | LogicalCondition
+  | FuzzyCondition
+  | ExpressionTuple;
+
+/**
+ * Expression - semantic alias for Condition when used in numeric/value contexts
+ *
+ * While Condition implies boolean evaluation (true/false), Expression is used
+ * when the same structure evaluates to a numeric or other value type.
+ *
+ * Examples:
+ * - Condition: ['eq', '$age', 18] -> boolean
+ * - Expression: ['mult', 10, '$years'] -> number
+ * - Expression: ['add', '$base', '$bonus'] -> number
+ */
+export type Expression = Condition;
+
+// ========================================
+// Compiled Types
+// ========================================
+
+export type CompiledPath = {
+  param: string;
+  path: string[];
+};
+
+export type CompiledOperand =
+  | { type: "property"; ref: CompiledPath }
+  | { type: "constant"; value: any }
+  | { type: "function"; fn: string; args: CompiledOperand[] }
+  | { type: "expression"; compiled: CompiledCondition };
+
+export type CompiledCondition = {
+  op: string;
+  arity: "unary" | "binary" | "ternary" | "variadic";
+  operands?: CompiledOperand[];
+  children?: CompiledCondition[];
+};

package/src/core/types/fact.ts

@@ -0,0 +1,26 @@
+/**
+ * Core fact types - shared across all engines
+ */
+
+export type FactInput = {
+  id?: string;
+  type: string;
+  data: Record<string, any>;
+};
+
+export type Fact = {
+  id: string;
+  type: string;
+  data: Record<string, any>;
+};
+
+export type FactChange = {
+  action: 'add' | 'remove' | 'update';
+  fact: Fact;
+  previous?: Fact;
+};
+
+/**
+ * Binding context maps parameter names to facts
+ */
+export type BindingContext = Record<string, Fact>;

package/src/core/types/index.ts

@@ -0,0 +1,55 @@
+/**
+ * Core types - shared across all engines
+ */
+
+// Fact types
+export {
+  Fact,
+  FactInput,
+  FactChange,
+  BindingContext
+} from './fact';
+
+// Schema types
+export {
+  JSONSchema,
+  ShapeShorthand,
+  Shape
+} from './schema';
+
+// Condition and operator types
+export {
+  PropertyRef,
+  FunctionExpr,
+  UnitValue,
+  ConstantValue,
+  Operand,
+  UnaryCondition,
+  BinaryCondition,
+  TernaryCondition,
+  LogicalCondition,
+  FuzzyCondition,
+  ExpressionTuple,
+  Condition,
+  Expression,
+  UnaryOperator,
+  BinaryOperator,
+  TernaryOperator,
+  VariadicOperator,
+  Operator,
+  CompiledPath,
+  CompiledOperand,
+  CompiledCondition
+} from './condition';
+
+// Rule types
+export {
+  InputParameter,
+  RuleSetMode,
+  ValidityDuration,
+  BaseRule,
+  BaseRuleSet,
+  CompiledInputParameter,
+  CompiledBaseRule,
+  CompiledBaseRuleSet
+} from './rule';

package/src/core/types/rule.ts

@@ -0,0 +1,108 @@
+/**
+ * Core rule types - shared across all engines
+ *
+ * This defines the base rule structure that all engine-specific rules extend.
+ */
+
+import { Condition, CompiledCondition, CompiledPath } from './condition';
+import { JSONSchema, Shape } from './schema';
+
+// ========================================
+// Parameter Types
+// ========================================
+
+export type InputParameter = {
+  name: string;
+  type: string;
+  shape?: Shape;
+  where?: Condition;
+  from?: string;
+};
+
+// ========================================
+// Temporal Validity Types
+// ========================================
+
+/**
+ * Relative duration for rule validity
+ * Used with validFor to specify "valid for X days/months from Y"
+ */
+export type ValidityDuration = {
+  days?: number;
+  months?: number;
+  from: string;  // '$ruleset.lastModified' | '$ruleset.createdAt' | ISO date string
+};
+
+// ========================================
+// Base Rule Types
+// ========================================
+
+export type RuleSetMode = "forward" | "scoring" | "backward" | "sequential" | "fuzzy" | "bayesian" | "monte-carlo" | "state-machine" | "constraint" | "utility" | "defeasible" | "expert" | "pricing";
+
+export type BaseRule = {
+  id: string;           // Unique identifier (system-generated or explicit)
+  name?: string;        // Optional human-readable name
+  salience?: number;
+  inputs: InputParameter[];
+  when?: Condition;     // Join condition (renamed from 'where' for better readability)
+
+  // Temporal validity - rule is only active within these bounds
+  validFrom?: string;   // ISO date string - rule activates on this date
+  validUntil?: string;  // ISO date string - rule expires after this date
+  validFor?: ValidityDuration;  // Relative duration from a reference date
+};
+
+export type BaseRuleSet = {
+  id: string;           // Unique identifier
+  name?: string;        // Optional human-readable name
+  mode: RuleSetMode;
+  shape?: Shape;
+
+  // Ruleset metadata - accessible via $ruleset in conditions
+  version?: string;       // Semantic version (e.g., '1.2.0')
+  lastModified?: string;  // ISO date - when ruleset was last changed
+  createdAt?: string;     // ISO date - when ruleset was created
+};
+
+// ========================================
+// Compiled Parameter Types
+// ========================================
+
+export type CompiledInputParameter = {
+  name: string;
+  type: string;
+  schema: JSONSchema;
+  where?: CompiledCondition;
+  from?: CompiledPath;
+};
+
+// ========================================
+// Compiled Base Rule Types
+// ========================================
+
+export type CompiledBaseRule = {
+  id: string;           // Unique identifier
+  name?: string;        // Optional human-readable name
+  salience: number;
+  complexity: number;
+  index: number;
+  inputs: CompiledInputParameter[];
+  when?: CompiledCondition;  // Compiled join condition
+
+  // Temporal validity (preserved from source)
+  validFrom?: string;
+  validUntil?: string;
+  validFor?: ValidityDuration;
+};
+
+export type CompiledBaseRuleSet = {
+  id: string;           // Unique identifier
+  name?: string;        // Optional human-readable name
+  mode: RuleSetMode;
+  schema: JSONSchema;
+
+  // Ruleset metadata (preserved from source)
+  version?: string;
+  lastModified?: string;
+  createdAt?: string;
+};

package/src/core/types/schema.ts

@@ -0,0 +1,18 @@
+/**
+ * Core schema types - shared across all engines
+ */
+
+export type JSONSchema = {
+  type: "string" | "number" | "boolean" | "object" | "array" | "date";
+  properties?: Record<string, JSONSchema>;
+  items?: JSONSchema;
+  minimum?: number;
+  maximum?: number;
+  "x-unit"?: string;
+};
+
+export type ShapeShorthand =
+  | string
+  | { [key: string]: ShapeShorthand };
+
+export type Shape = ShapeShorthand | JSONSchema;

package/src/engines/backward/compiler.ts

@@ -0,0 +1,118 @@
+/**
+ * Backward Chaining Engine Compiler
+ */
+
+import {
+  compileCondition,
+  normalizeShape
+} from '../../core';
+
+import {
+  BackwardRule,
+  BackwardRuleSet,
+  BackwardConfig,
+  CompiledBackwardRule,
+  CompiledBackwardRuleSet,
+  CompiledBackwardAction
+} from './types';
+
+const DEFAULT_MAX_DEPTH = 100;
+
+// ========================================
+// Helper Functions
+// ========================================
+
+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;
+}
+
+function calculateComplexity(inputs: any[], where?: any): number {
+  let score = 0;
+  score += inputs.length * 10;
+  score += countConditions(where) * 5;
+  for (const input of inputs) {
+    score += countConditions(input.where) * 2;
+  }
+  return score;
+}
+
+function compilePath(from: string) {
+  const str = from.startsWith('$') ? from.slice(1) : from;
+  const parts = str.split('.');
+  return {
+    param: parts[0],
+    path: parts.slice(1)
+  };
+}
+
+// ========================================
+// Parameter Compilation
+// ========================================
+
+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;
+}
+
+// ========================================
+// Rule Compilation
+// ========================================
+
+export function compileBackwardRule(rule: BackwardRule, index: number = 0): CompiledBackwardRule {
+  const inputs = rule.inputs.map(compileInputParameter);
+  const when = rule.when ? compileCondition(rule.when) : undefined;
+
+  const action: CompiledBackwardAction = {
+    mode: 'backward',
+    prove: rule.prove,
+    requires: rule.requires ?? []
+  };
+
+  return {
+    id: rule.id,
+    name: rule.name,
+    salience: rule.salience ?? 0,
+    complexity: calculateComplexity(inputs, when),
+    index,
+    inputs,
+    when,
+    action
+  };
+}
+
+// ========================================
+// RuleSet Compilation
+// ========================================
+
+export function compileBackwardRuleSet(ruleSet: BackwardRuleSet): CompiledBackwardRuleSet {
+  const config: BackwardConfig = {
+    mode: 'backward',
+    maxDepth: ruleSet.config?.maxDepth ?? DEFAULT_MAX_DEPTH
+  };
+
+  return {
+    id: ruleSet.id,
+    name: ruleSet.name,
+    mode: 'backward',
+    schema: ruleSet.shape ? normalizeShape(ruleSet.shape) : { type: 'object' },
+    rules: ruleSet.rules.map((rule, index) => compileBackwardRule(rule, index)),
+    config
+  };
+}

package/src/engines/backward/engine.ts

@@ -0,0 +1,123 @@
+/**
+ * Backward Chaining Engine
+ *
+ * Self-contained engine for backward chaining (goal-driven) rule execution.
+ * Implements IRuleEngine with strongly-typed ruleset, options, and result.
+ */
+
+import {
+  IRuleEngine,
+  WorkingMemory,
+  Fact,
+  FactInput,
+  FactChange
+} from '../../core';
+
+import {
+  CompiledBackwardRuleSet,
+  BackwardOptions,
+  BackwardResult
+} from './types';
+
+import { BackwardChainingStrategy } from './strategy';
+
+/**
+ * Backward chaining rule engine.
+ *
+ * Executes rules in a goal-driven manner, starting with a goal to prove
+ * and working backward to find rules and facts that support it.
+ *
+ * @example
+ * ```typescript
+ * const engine = new BackwardEngine();
+ * engine.add({ type: 'Customer', data: { tier: 'platinum', spend: 15000 } });
+ *
+ * const result = engine.execute(compiledRules, {
+ *   goal: 'eligible-for-premium-discount'
+ * });
+ *
+ * if (result.proven) {
+ *   console.log('Customer is eligible!');
+ * }
+ * ```
+ */
+export class BackwardEngine implements IRuleEngine<CompiledBackwardRuleSet, BackwardOptions, BackwardResult> {
+  private wm: WorkingMemory;
+  private strategy: BackwardChainingStrategy;
+
+  constructor(workingMemory?: WorkingMemory) {
+    this.wm = workingMemory ?? new WorkingMemory();
+    this.strategy = new BackwardChainingStrategy();
+  }
+
+  // ========================================
+  // 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 backward chaining ruleset to prove a goal.
+   *
+   * @param ruleSet - Compiled backward ruleset
+   * @param options - Runtime options including the goal to prove
+   * @returns Result indicating if goal was proven and the proof path
+   */
+  execute(ruleSet: CompiledBackwardRuleSet, options: BackwardOptions): BackwardResult {
+    return this.strategy.run(ruleSet, this.wm, options);
+  }
+
+  // ========================================
+  // Utility Methods
+  // ========================================
+
+  getWorkingMemory(): WorkingMemory {
+    return this.wm;
+  }
+}

package/src/engines/backward/index.ts

@@ -0,0 +1,39 @@
+/**
+ * Backward Chaining Engine
+ *
+ * Provides backward chaining (goal-driven) rule execution.
+ * Given a goal to prove, finds rules that can prove it and
+ * checks if their conditions are satisfied by facts in working memory.
+ */
+
+// Types
+export {
+  // Source types
+  BackwardRule,
+  BackwardRuleSet,
+  BackwardConfig,
+  // Compiled types
+  CompiledBackwardAction,
+  CompiledBackwardRule,
+  CompiledBackwardRuleSet,
+  // Runtime types
+  ProofStep,
+  ProofResult,
+  BackwardOptions,
+  BackwardResult
+} from './types';
+
+// Compiler
+export {
+  compileBackwardRule,
+  compileBackwardRuleSet
+} from './compiler';
+
+// Strategy
+export {
+  BackwardChainingStrategy,
+  backwardStrategy
+} from './strategy';
+
+// Engine
+export { BackwardEngine } from './engine';