@higher.archi/boe 1.0.0

package/src/core/memory/working-memory.interface.ts

@@ -0,0 +1,95 @@
+/**
+ * Core working memory interface - shared across all engines
+ */
+
+import { Fact, FactInput, FactChange } from '../types';
+
+/**
+ * Interface for working memory implementations.
+ *
+ * This interface defines the contract for fact management in the rule engine.
+ * Both WorkingMemory and RuleEngine should implement this interface to ensure
+ * they stay in sync and provide consistent fact management APIs.
+ */
+export interface IWorkingMemory {
+  /**
+   * Add a new fact to working memory.
+   * If a fact with the same ID already exists, it will be updated instead.
+   *
+   * @param input - The fact to add (id is optional, will be auto-generated if not provided)
+   * @returns The added fact with its ID
+   */
+  add(input: FactInput): Fact;
+
+  /**
+   * Remove a fact from working memory by its ID.
+   *
+   * @param factId - The ID of the fact to remove
+   * @returns The removed fact, or undefined if not found
+   */
+  remove(factId: string): Fact | undefined;
+
+  /**
+   * Update an existing fact in working memory.
+   * If the fact doesn't exist, it will be added instead.
+   *
+   * @param input - The fact to update (must include id)
+   * @returns The updated fact
+   */
+  update(input: FactInput): Fact;
+
+  /**
+   * Get a fact by its ID.
+   *
+   * @param factId - The ID of the fact to retrieve
+   * @returns The fact, or undefined if not found
+   */
+  get(factId: string): Fact | undefined;
+
+  /**
+   * Get all facts of a specific type.
+   *
+   * @param type - The type of facts to retrieve
+   * @returns Array of facts matching the type
+   */
+  getByType(type: string): Fact[];
+
+  /**
+   * Get all facts in working memory.
+   *
+   * @returns Array of all facts
+   */
+  getAll(): Fact[];
+
+  /**
+   * Check if a fact exists in working memory.
+   *
+   * @param factId - The ID of the fact to check
+   * @returns True if the fact exists, false otherwise
+   */
+  has(factId: string): boolean;
+
+  /**
+   * Get the number of facts in working memory.
+   *
+   * @returns The total number of facts
+   */
+  size(): number;
+
+  /**
+   * Clear all facts from working memory.
+   */
+  clear(): void;
+
+  /**
+   * Get the history of changes made to working memory.
+   *
+   * @returns Array of changes (add, remove, update operations)
+   */
+  getChanges(): FactChange[];
+
+  /**
+   * Clear the change history.
+   */
+  clearChanges(): void;
+}

package/src/core/memory/working-memory.ts

@@ -0,0 +1,123 @@
+/**
+ * Core working memory implementation - shared across all engines
+ */
+
+import { IWorkingMemory } from './working-memory.interface';
+import { Fact, FactInput, FactChange } from '../types';
+
+export class WorkingMemory implements IWorkingMemory {
+  private facts: Map<string, Fact> = new Map();
+  private byType: Map<string, Set<string>> = new Map();
+  private changes: FactChange[] = [];
+  private counters: Map<string, number> = new Map();
+
+  private generateId(type: string): string {
+    const count = (this.counters.get(type) ?? 0) + 1;
+    this.counters.set(type, count);
+    return `${type}:${count}`;
+  }
+
+  add(input: FactInput): Fact {
+    const fact: Fact = {
+      id: input.id ?? this.generateId(input.type),
+      type: input.type,
+      data: input.data
+    };
+
+    if (this.facts.has(fact.id)) {
+      return this.update(fact);
+    }
+
+    this.facts.set(fact.id, fact);
+    this.indexByType(fact);
+    this.changes.push({ action: 'add', fact });
+
+    return fact;
+  }
+
+  remove(factId: string): Fact | undefined {
+    const fact = this.facts.get(factId);
+    if (!fact) return undefined;
+
+    this.facts.delete(factId);
+    this.removeFromTypeIndex(fact);
+    this.changes.push({ action: 'remove', fact });
+
+    return fact;
+  }
+
+  update(input: FactInput): Fact {
+    if (!input.id) {
+      return this.add(input);
+    }
+
+    const previous = this.facts.get(input.id);
+    if (!previous) {
+      return this.add(input);
+    }
+
+    const fact: Fact = {
+      id: input.id,
+      type: input.type,
+      data: input.data
+    };
+
+    if (previous.type !== fact.type) {
+      this.removeFromTypeIndex(previous);
+      this.indexByType(fact);
+    }
+
+    this.facts.set(fact.id, fact);
+    this.changes.push({ action: 'update', fact, previous });
+
+    return fact;
+  }
+
+  get(factId: string): Fact | undefined {
+    return this.facts.get(factId);
+  }
+
+  getByType(type: string): Fact[] {
+    const ids = this.byType.get(type);
+    if (!ids) return [];
+    return Array.from(ids).map(id => this.facts.get(id)!);
+  }
+
+  getAll(): Fact[] {
+    return Array.from(this.facts.values());
+  }
+
+  has(factId: string): boolean {
+    return this.facts.has(factId);
+  }
+
+  size(): number {
+    return this.facts.size;
+  }
+
+  clear(): void {
+    this.facts.clear();
+    this.byType.clear();
+    this.changes = [];
+    this.counters.clear();
+  }
+
+  getChanges(): FactChange[] {
+    return this.changes;
+  }
+
+  clearChanges(): void {
+    this.changes = [];
+  }
+
+  private indexByType(fact: Fact): void {
+    if (!this.byType.has(fact.type)) {
+      this.byType.set(fact.type, new Set());
+    }
+    this.byType.get(fact.type)!.add(fact.id);
+  }
+
+  private removeFromTypeIndex(fact: Fact): void {
+    this.byType.get(fact.type)?.delete(fact.id);
+  }
+}

package/src/core/operators/adapters/context.adapter.ts

@@ -0,0 +1,53 @@
+/**
+ * Context Adapter
+ *
+ * Bridges the existing BindingContext (fact-based) to the new
+ * EvaluationContext (variable-based) for backward compatibility.
+ */
+
+import { EvaluationContext } from '../evaluator';
+
+/**
+ * Fact type from core types (minimal definition for decoupling)
+ */
+export interface Fact {
+  id: string;
+  type: string;
+  data: Record<string, any>;
+}
+
+/**
+ * BindingContext from core types
+ */
+export type BindingContext = Record<string, Fact>;
+
+/**
+ * Convert a BindingContext to an EvaluationContext
+ *
+ * Maps fact parameter names to their data objects for variable resolution.
+ */
+export function bindingToEvaluationContext(binding: BindingContext): EvaluationContext {
+  const variables: Record<string, unknown> = {};
+
+  for (const [paramName, fact] of Object.entries(binding)) {
+    // Make the fact's data available under the parameter name
+    variables[paramName] = fact.data;
+    // Also provide access to the full fact object
+    variables[`${paramName}$fact`] = fact;
+  }
+
+  return {
+    variables,
+  };
+}
+
+/**
+ * Create an EvaluationContext from raw variables
+ *
+ * For use when you have direct key-value pairs rather than facts.
+ */
+export function createEvaluationContext(
+  variables: Record<string, unknown> = {}
+): EvaluationContext {
+  return { variables };
+}

package/src/core/operators/adapters/index.ts

@@ -0,0 +1,25 @@
+/**
+ * Adapters Index
+ *
+ * Drop-in replacements for integrating the new operator system
+ * with existing code.
+ */
+
+// Context adapter
+export {
+  bindingToEvaluationContext,
+  createEvaluationContext,
+  type Fact,
+  type BindingContext,
+} from './context.adapter';
+
+// Operator adapter
+export {
+  OperatorAdapter,
+  getDefaultAdapter,
+  getOperator,
+  getArithmeticOperator,
+  createAdapter,
+  resetDefaultAdapter,
+  type OperatorFn,
+} from './operator.adapter';

package/src/core/operators/adapters/operator.adapter.ts

@@ -0,0 +1,173 @@
+/**
+ * Operator Adapter
+ *
+ * Provides drop-in replacement functions that match the existing
+ * operator registry interface while using the new operator system.
+ */
+
+import { OperatorRegistry } from '../registry';
+import { OperatorEvaluator } from '../evaluator';
+import { createDefaultRegistry } from '../index';
+import { BindingContext, bindingToEvaluationContext } from './context.adapter';
+import { ParameterType } from '../types';
+
+/**
+ * Operator function type (matches existing OperatorFn)
+ */
+export type OperatorFn = (...args: any[]) => any;
+
+/**
+ * Adapter that wraps the new operator system to provide
+ * the same interface as the existing operator registry.
+ */
+export class OperatorAdapter {
+  private evaluator: OperatorEvaluator;
+
+  constructor(private registry: OperatorRegistry) {
+    this.evaluator = new OperatorEvaluator(registry);
+  }
+
+  /**
+   * Get an operator function by name.
+   *
+   * This replaces the existing getOperator(type, op) function.
+   * The type parameter is kept for API compatibility but the new system
+   * infers type from arguments at runtime.
+   */
+  getOperator(_type: string, op: string): OperatorFn | null {
+    const operator = this.registry.get(op);
+    if (!operator) return null;
+
+    // Return a function that evaluates using the new system
+    return (...args: any[]) => {
+      const result = this.evaluator.evaluate(op, args);
+      if (!result.success) {
+        throw new Error(result.error);
+      }
+      return result.value;
+    };
+  }
+
+  /**
+   * Get an arithmetic operator function by name.
+   *
+   * This replaces the existing getArithmeticOperator(op) function.
+   */
+  getArithmeticOperator(op: string): OperatorFn | null {
+    return this.getOperator('number', op);
+  }
+
+  /**
+   * Evaluate an operator directly with arguments.
+   *
+   * Returns the result value or throws on error.
+   */
+  evaluate(op: string, args: unknown[]): unknown {
+    const result = this.evaluator.evaluate(op, args);
+    if (!result.success) {
+      throw new Error(result.error);
+    }
+    return result.value;
+  }
+
+  /**
+   * Evaluate an operator with a binding context.
+   *
+   * Converts the binding context to evaluation context for variable resolution.
+   */
+  evaluateWithContext(
+    op: string,
+    args: unknown[],
+    context: BindingContext
+  ): unknown {
+    const evalContext = bindingToEvaluationContext(context);
+    const result = this.evaluator.evaluate(op, args, evalContext);
+    if (!result.success) {
+      throw new Error(result.error);
+    }
+    return result.value;
+  }
+
+  /**
+   * Validate an operator call at compile time.
+   */
+  validate(op: string, argCount: number, argTypes?: ParameterType[]) {
+    return this.registry.validate(op, argCount, argTypes);
+  }
+
+  /**
+   * Check if an operator exists.
+   */
+  has(op: string): boolean {
+    return this.registry.has(op);
+  }
+
+  /**
+   * Get the underlying registry.
+   */
+  getRegistry(): OperatorRegistry {
+    return this.registry;
+  }
+
+  /**
+   * Get the underlying evaluator.
+   */
+  getEvaluator(): OperatorEvaluator {
+    return this.evaluator;
+  }
+}
+
+// ============================================================
+// Drop-in replacement functions
+// ============================================================
+
+/**
+ * Default adapter instance using the default registry
+ */
+let defaultAdapter: OperatorAdapter | null = null;
+
+/**
+ * Get or create the default adapter
+ */
+export function getDefaultAdapter(): OperatorAdapter {
+  if (!defaultAdapter) {
+    defaultAdapter = new OperatorAdapter(createDefaultRegistry());
+  }
+  return defaultAdapter;
+}
+
+/**
+ * Drop-in replacement for existing getOperator function.
+ *
+ * Usage:
+ *   import { getOperator } from '../operators/adapters';
+ */
+export function getOperator(type: string, op: string): OperatorFn | null {
+  return getDefaultAdapter().getOperator(type, op);
+}
+
+/**
+ * Drop-in replacement for existing getArithmeticOperator function.
+ *
+ * Usage:
+ *   import { getArithmeticOperator } from '../operators/adapters';
+ */
+export function getArithmeticOperator(op: string): OperatorFn | null {
+  return getDefaultAdapter().getArithmeticOperator(op);
+}
+
+/**
+ * Create a new adapter with a custom registry.
+ *
+ * Useful for engines that need custom operators (like state machine).
+ */
+export function createAdapter(registry: OperatorRegistry): OperatorAdapter {
+  return new OperatorAdapter(registry);
+}
+
+/**
+ * Reset the default adapter (for testing)
+ */
+export function resetDefaultAdapter(): void {
+  defaultAdapter = null;
+}

package/src/core/operators/arithmetic/add.ts

@@ -0,0 +1,44 @@
+/**
+ * Add Operator
+ *
+ * Addition operations for numbers and string concatenation.
+ */
+
+import { polymorphicOp, variadicOp } from '../operator';
+import { Operator, PolymorphicOperator } from '../types';
+
+/**
+ * Add operator (binary) - adds two numbers or concatenates strings
+ */
+export const add: PolymorphicOperator = polymorphicOp(
+  'add',
+  {
+    number: (a: number, b: number) => a + b,
+    string: (a: string, b: string) => a + b,
+    any: (a: any, b: any) => a + b,
+  },
+  {
+    arity: 'binary',
+    returns: 'any',
+    category: 'arithmetic',
+    description: 'Adds two numbers or concatenates two strings',
+    aliases: ['plus', '+'],
+  }
+);
+
+/**
+ * Sum operator (variadic) - adds all numbers
+ */
+export const sum: Operator = variadicOp<number>(
+  'sum',
+  (...args) => args.reduce((acc, val) => acc + val, 0),
+  {
+    paramType: 'number',
+    returns: 'number',
+    category: 'arithmetic',
+    description: 'Adds all numbers together',
+    aliases: ['total'],
+  }
+);
+
+export default [add, sum];

package/src/core/operators/arithmetic/average.ts

@@ -0,0 +1,25 @@
+/**
+ * Average Operator
+ *
+ * Statistical average operations.
+ */
+
+import { variadicOp } from '../operator';
+import { Operator } from '../types';
+
+/**
+ * Average operator - calculates arithmetic mean
+ */
+export const average: Operator = variadicOp<number>(
+  'average',
+  (...args) => args.reduce((acc, val) => acc + val, 0) / args.length,
+  {
+    paramType: 'number',
+    returns: 'number',
+    category: 'arithmetic',
+    description: 'Calculates the arithmetic mean of all numbers',
+    aliases: ['avg', 'mean'],
+  }
+);
+
+export default [average];

package/src/core/operators/arithmetic/divide.ts

@@ -0,0 +1,42 @@
+/**
+ * Divide Operator
+ *
+ * Division operations for numbers.
+ */
+
+import { binaryOp } from '../operator';
+import { Operator } from '../types';
+
+/**
+ * Divide operator - divides first number by second
+ */
+export const divide: Operator = binaryOp<number>(
+  'divide',
+  (a, b) => a / b,
+  {
+    leftType: 'number',
+    rightType: 'number',
+    returns: 'number',
+    category: 'arithmetic',
+    description: 'Divides the first number by the second',
+    aliases: ['div', '/'],
+  }
+);
+
+/**
+ * Modulo operator - returns remainder of division
+ */
+export const modulo: Operator = binaryOp<number>(
+  'modulo',
+  (a, b) => a % b,
+  {
+    leftType: 'number',
+    rightType: 'number',
+    returns: 'number',
+    category: 'arithmetic',
+    description: 'Returns the remainder of dividing first number by second',
+    aliases: ['mod', '%'],
+  }
+);
+
+export default [divide, modulo];

package/src/core/operators/arithmetic/index.ts

@@ -0,0 +1,42 @@
+/**
+ * Arithmetic Operators
+ *
+ * Exports all arithmetic operators for registry registration.
+ */
+
+import addOps from './add';
+import subtractOps from './subtract';
+import multiplyOps from './multiply';
+import divideOps from './divide';
+import powerOps from './power';
+import minMaxOps from './min-max';
+import roundingOps from './rounding';
+import averageOps from './average';
+import numberChecksOps from './number-checks';
+
+export * from './add';
+export * from './subtract';
+export * from './multiply';
+export * from './divide';
+export * from './power';
+export * from './min-max';
+export * from './rounding';
+export * from './average';
+export * from './number-checks';
+
+/**
+ * All arithmetic operators as an array for bulk registration
+ */
+export const arithmeticOperators = [
+  ...addOps,
+  ...subtractOps,
+  ...multiplyOps,
+  ...divideOps,
+  ...powerOps,
+  ...minMaxOps,
+  ...roundingOps,
+  ...averageOps,
+  ...numberChecksOps,
+];
+
+export default arithmeticOperators;

package/src/core/operators/arithmetic/min-max.ts

@@ -0,0 +1,70 @@
+/**
+ * Min/Max Operators
+ *
+ * Operations to find minimum and maximum values.
+ */
+
+import { binaryOp, variadicOp } from '../operator';
+import { Operator } from '../types';
+
+/**
+ * Min operator (binary) - returns smaller of two numbers
+ */
+export const min: Operator = binaryOp<number>(
+  'min',
+  (a, b) => Math.min(a, b),
+  {
+    leftType: 'number',
+    rightType: 'number',
+    returns: 'number',
+    category: 'arithmetic',
+    description: 'Returns the smaller of two numbers',
+  }
+);
+
+/**
+ * Max operator (binary) - returns larger of two numbers
+ */
+export const max: Operator = binaryOp<number>(
+  'max',
+  (a, b) => Math.max(a, b),
+  {
+    leftType: 'number',
+    rightType: 'number',
+    returns: 'number',
+    category: 'arithmetic',
+    description: 'Returns the larger of two numbers',
+  }
+);
+
+/**
+ * Min all operator (variadic) - returns smallest of all numbers
+ */
+export const minAll: Operator = variadicOp<number>(
+  'minAll',
+  (...args) => Math.min(...args),
+  {
+    paramType: 'number',
+    returns: 'number',
+    category: 'arithmetic',
+    description: 'Returns the smallest of all numbers',
+    aliases: ['minimum'],
+  }
+);
+
+/**
+ * Max all operator (variadic) - returns largest of all numbers
+ */
+export const maxAll: Operator = variadicOp<number>(
+  'maxAll',
+  (...args) => Math.max(...args),
+  {
+    paramType: 'number',
+    returns: 'number',
+    category: 'arithmetic',
+    description: 'Returns the largest of all numbers',
+    aliases: ['maximum'],
+  }
+);
+
+export default [min, max, minAll, maxAll];