@higher.archi/boe 1.0.0

package/src/core/evaluation/condition.evaluator.ts

@@ -0,0 +1,185 @@
+/**
+ * Core condition evaluator - shared across all engines
+ */
+
+import { getOperator, getArithmeticOperator } from '../operators/adapters';
+import { CompiledCondition, CompiledOperand, BindingContext } from '../types';
+
+// ========================================
+// Path Utilities
+// ========================================
+
+function getValueAtPath(obj: any, path: string[]): any {
+  let current = obj;
+  for (const key of path) {
+    if (current === null || current === undefined) return undefined;
+    current = current[key];
+  }
+  return current;
+}
+
+/**
+ * Set a value at a nested path, auto-creating intermediate objects
+ */
+export function setValueAtPath(obj: any, path: string[], value: any): void {
+  if (path.length === 0) return;
+
+  let current = obj;
+  for (let i = 0; i < path.length - 1; i++) {
+    const key = path[i];
+    if (current[key] === null || current[key] === undefined) {
+      current[key] = {};  // Auto-create intermediate objects
+    }
+    current = current[key];
+  }
+
+  current[path[path.length - 1]] = value;
+}
+
+// ========================================
+// Operand Resolution
+// ========================================
+
+export function resolveOperand(operand: CompiledOperand, context: BindingContext): any {
+  switch (operand.type) {
+    case 'constant':
+      return operand.value;
+
+    case 'property': {
+      const fact = context[operand.ref.param];
+      if (!fact) return undefined;
+      if (operand.ref.path.length === 0) return fact.data;
+      return getValueAtPath(fact.data, operand.ref.path);
+    }
+
+    case 'function':
+      // TODO: implement function registry
+      throw new Error(`Function expressions not yet implemented: ${operand.fn}`);
+
+    case 'expression':
+      // Recursively evaluate the compiled expression
+      // This handles nested expressions like ['multiply', '$app.amount', 1.5]
+      return evaluateExpression(operand.compiled, context);
+  }
+}
+
+function getValueType(value: any): string {
+  if (value === null) return 'any';
+  if (value === undefined) return 'any';
+  if (Array.isArray(value)) return 'array';
+  if (value instanceof Date) return 'date';
+  return typeof value;
+}
+
+export function evaluateCondition(condition: CompiledCondition, context: BindingContext): boolean {
+  const { op, arity, operands, children } = condition;
+
+  // Logical operators
+  if (op === 'and') {
+    return children!.every(child => evaluateCondition(child, context));
+  }
+
+  if (op === 'or') {
+    return children!.some(child => evaluateCondition(child, context));
+  }
+
+  if (op === 'not') {
+    return !evaluateCondition(children![0], context);
+  }
+
+  if (op === 'xor') {
+    const a = evaluateCondition(children![0], context);
+    const b = evaluateCondition(children![1], context);
+    return (a || b) && !(a && b);
+  }
+
+  // Variadic equals: ['equals', x, a, b, c] means x == a OR x == b OR x == c
+  if (arity === 'variadic' && op === 'equals') {
+    const values = operands!.map(o => resolveOperand(o, context));
+    const target = values[0];
+    const candidates = values.slice(1);
+    return candidates.some(c => target === c);
+  }
+
+  // Variadic notEquals: ['notEquals', x, a, b, c] means x != a AND x != b AND x != c
+  if (arity === 'variadic' && op === 'notEquals') {
+    const values = operands!.map(o => resolveOperand(o, context));
+    const target = values[0];
+    const candidates = values.slice(1);
+    return candidates.every(c => target !== c);
+  }
+
+  // Value operators
+  if (arity === 'unary') {
+    const value = resolveOperand(operands![0], context);
+    const type = getValueType(value);
+    const fn = getOperator(type, op);
+    if (!fn) throw new Error(`No operator '${op}' for type '${type}'`);
+    return fn(value);
+  }
+
+  if (arity === 'binary') {
+    const left = resolveOperand(operands![0], context);
+    const right = resolveOperand(operands![1], context);
+    const type = getValueType(left);
+    const fn = getOperator(type, op);
+    if (!fn) throw new Error(`No operator '${op}' for type '${type}'`);
+    return fn(left, right);
+  }
+
+  if (arity === 'ternary') {
+    const first = resolveOperand(operands![0], context);
+    const second = resolveOperand(operands![1], context);
+    const third = resolveOperand(operands![2], context);
+    const type = getValueType(first);
+    const fn = getOperator(type, op);
+    if (!fn) throw new Error(`No operator '${op}' for type '${type}'`);
+    return fn(first, second, third);
+  }
+
+  throw new Error(`Unknown arity: ${arity}`);
+}
+
+/**
+ * Evaluate an expression (CompiledCondition used in value context)
+ * Returns the computed value (number, string, etc.) rather than boolean
+ *
+ * This handles arithmetic operators like 'add', 'multiply', 'subtract', etc.
+ */
+export function evaluateExpression(expr: CompiledCondition, context: BindingContext): any {
+  const { op, arity, operands } = expr;
+
+  // For arithmetic/value operators, resolve operands and apply operator
+  if (arity === 'unary' && operands) {
+    const value = resolveOperand(operands[0], context);
+    const fn = getArithmeticOperator(op);
+    if (fn) return fn(value);
+    // Fall back to regular operator if no arithmetic operator found
+    const opFn = getOperator(getValueType(value), op);
+    if (opFn) return opFn(value);
+    throw new Error(`No operator '${op}' found`);
+  }
+
+  if (arity === 'binary' && operands) {
+    const left = resolveOperand(operands[0], context);
+    const right = resolveOperand(operands[1], context);
+    const fn = getArithmeticOperator(op);
+    if (fn) return fn(left, right);
+    // Fall back to regular operator if no arithmetic operator found
+    const opFn = getOperator(getValueType(left), op);
+    if (opFn) return opFn(left, right);
+    throw new Error(`No operator '${op}' found`);
+  }
+
+  if (arity === 'ternary' && operands) {
+    const first = resolveOperand(operands[0], context);
+    const second = resolveOperand(operands[1], context);
+    const third = resolveOperand(operands[2], context);
+    // Fall back to regular operator
+    const opFn = getOperator(getValueType(first), op);
+    if (opFn) return opFn(first, second, third);
+    throw new Error(`No operator '${op}' found`);
+  }
+
+  throw new Error(`Cannot evaluate expression with op='${op}' and arity='${arity}'`);
+}

package/src/core/evaluation/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Core evaluation module - shared across all engines
+ */
+
+export {
+  evaluateCondition,
+  evaluateExpression,
+  resolveOperand,
+  setValueAtPath
+} from './condition.evaluator';
+
+// Temporal validity utilities
+export {
+  injectRulesetContext,
+  injectTemporalContext,  // deprecated, use injectRulesetContext
+  isRuleTemporallyValid,
+  filterTemporallyValidRules,
+  getRuleTemporalInfo,
+  RulesetMetadata
+} from './temporal';

package/src/core/evaluation/temporal.ts

@@ -0,0 +1,222 @@
+/**
+ * Temporal validity utilities for rule evaluation
+ *
+ * Provides:
+ * - $ruleset meta-variable injection
+ * - $now built-in variable injection
+ * - Rule filtering based on validFrom/validUntil/validFor
+ */
+
+import { BindingContext, Fact } from '../types/fact';
+import { CompiledBaseRuleSet, CompiledBaseRule, ValidityDuration } from '../types/rule';
+
+// ========================================
+// Context Injection
+// ========================================
+
+/**
+ * Ruleset metadata fact for $ruleset variable access
+ */
+export type RulesetMetadata = {
+  id: string;
+  name?: string;
+  mode: string;
+  version?: string;
+  lastModified?: string;
+  createdAt?: string;
+};
+
+/**
+ * Inject $ruleset into the binding context
+ * This allows rules to reference $ruleset.lastModified, $ruleset.version, etc.
+ *
+ * Note: For current time, use $temporal.now (see temporal.md documentation)
+ */
+export function injectRulesetContext(
+  context: BindingContext,
+  ruleset: CompiledBaseRuleSet
+): BindingContext {
+  // Create a shallow copy to avoid mutating original context
+  const enrichedContext: BindingContext = { ...context };
+
+  // Inject $ruleset as a pseudo-fact
+  enrichedContext['ruleset'] = {
+    id: '__ruleset__',
+    type: 'RulesetMetadata',
+    data: {
+      id: ruleset.id,
+      name: ruleset.name,
+      mode: ruleset.mode,
+      version: ruleset.version,
+      lastModified: ruleset.lastModified,
+      createdAt: ruleset.createdAt,
+    },
+  } as Fact;
+
+  return enrichedContext;
+}
+
+/**
+ * @deprecated Use injectRulesetContext instead. For time access, use $temporal.now
+ */
+export function injectTemporalContext(
+  context: BindingContext,
+  ruleset: CompiledBaseRuleSet,
+  _now?: Date
+): BindingContext {
+  return injectRulesetContext(context, ruleset);
+}
+
+// ========================================
+// Rule Filtering
+// ========================================
+
+/**
+ * Resolve a reference like '$ruleset.lastModified' to an actual date
+ */
+function resolveFromReference(from: string, ruleset: CompiledBaseRuleSet): Date | null {
+  if (from === '$ruleset.lastModified') {
+    return ruleset.lastModified ? new Date(ruleset.lastModified) : null;
+  }
+  if (from === '$ruleset.createdAt') {
+    return ruleset.createdAt ? new Date(ruleset.createdAt) : null;
+  }
+  // Try parsing as ISO date string
+  const date = new Date(from);
+  return isNaN(date.getTime()) ? null : date;
+}
+
+/**
+ * Calculate the expiry date based on validFor duration
+ */
+function calculateExpiryDate(validFor: ValidityDuration, ruleset: CompiledBaseRuleSet): Date | null {
+  const fromDate = resolveFromReference(validFor.from, ruleset);
+  if (!fromDate) return null;
+
+  const expiryDate = new Date(fromDate);
+
+  if (validFor.days) {
+    expiryDate.setDate(expiryDate.getDate() + validFor.days);
+  }
+  if (validFor.months) {
+    expiryDate.setMonth(expiryDate.getMonth() + validFor.months);
+  }
+
+  return expiryDate;
+}
+
+/**
+ * Check if a rule is currently valid based on temporal constraints
+ */
+export function isRuleTemporallyValid<T extends CompiledBaseRule>(
+  rule: T,
+  ruleset: CompiledBaseRuleSet,
+  now?: Date
+): boolean {
+  const currentTime = now || new Date();
+
+  // Check validFrom - rule not yet active
+  if (rule.validFrom) {
+    const validFromDate = new Date(rule.validFrom);
+    if (currentTime < validFromDate) {
+      return false;
+    }
+  }
+
+  // Check validUntil - rule has expired
+  if (rule.validUntil) {
+    const validUntilDate = new Date(rule.validUntil);
+    if (currentTime > validUntilDate) {
+      return false;
+    }
+  }
+
+  // Check validFor - relative expiry
+  if (rule.validFor) {
+    const expiryDate = calculateExpiryDate(rule.validFor, ruleset);
+    if (expiryDate && currentTime > expiryDate) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Filter rules to only include those that are temporally valid
+ * Returns a new array with only active rules
+ */
+export function filterTemporallyValidRules<T extends CompiledBaseRule>(
+  rules: T[],
+  ruleset: CompiledBaseRuleSet,
+  now?: Date
+): T[] {
+  return rules.filter(rule => isRuleTemporallyValid(rule, ruleset, now));
+}
+
+/**
+ * Get temporal validity info for a rule (useful for debugging/introspection)
+ */
+export function getRuleTemporalInfo<T extends CompiledBaseRule>(
+  rule: T,
+  ruleset: CompiledBaseRuleSet,
+  now?: Date
+): {
+  isValid: boolean;
+  validFrom?: string;
+  validUntil?: string;
+  expiresAt?: string;
+  reason?: string;
+} {
+  const currentTime = now || new Date();
+
+  // Check validFrom
+  if (rule.validFrom) {
+    const validFromDate = new Date(rule.validFrom);
+    if (currentTime < validFromDate) {
+      return {
+        isValid: false,
+        validFrom: rule.validFrom,
+        reason: `Not yet active. Activates on ${rule.validFrom}`,
+      };
+    }
+  }
+
+  // Check validUntil
+  if (rule.validUntil) {
+    const validUntilDate = new Date(rule.validUntil);
+    if (currentTime > validUntilDate) {
+      return {
+        isValid: false,
+        validUntil: rule.validUntil,
+        reason: `Expired on ${rule.validUntil}`,
+      };
+    }
+  }
+
+  // Check validFor
+  if (rule.validFor) {
+    const expiryDate = calculateExpiryDate(rule.validFor, ruleset);
+    if (expiryDate) {
+      if (currentTime > expiryDate) {
+        return {
+          isValid: false,
+          expiresAt: expiryDate.toISOString(),
+          reason: `Expired on ${expiryDate.toISOString()} (${rule.validFor.days || 0} days, ${rule.validFor.months || 0} months from ${rule.validFor.from})`,
+        };
+      }
+      return {
+        isValid: true,
+        expiresAt: expiryDate.toISOString(),
+        validFrom: rule.validFrom,
+        validUntil: rule.validUntil,
+      };
+    }
+  }
+
+  return {
+    isValid: true,
+    validFrom: rule.validFrom,
+    validUntil: rule.validUntil,
+  };
+}

package/src/core/index.ts

@@ -0,0 +1,75 @@
+/**
+ * Core module - shared components across all engines
+ *
+ * This module provides the foundation for all rule engines:
+ * - Types (facts, conditions, rules, schemas)
+ * - Memory (working memory interface and implementation)
+ * - Operators (operator registry and functions)
+ * - Evaluation (condition and expression evaluation)
+ * - Matching (pattern matching and activations)
+ * - Resolution (conflict resolution strategies)
+ * - Shapes (schema normalization)
+ */
+
+// Types
+export * from './types';
+
+// Memory
+export * from './memory';
+
+// Operators - new formal operator type system
+export {
+  OperatorRegistry,
+  getOperator,
+  getArithmeticOperator,
+  OperatorAdapter,
+  getDefaultAdapter,
+  createAdapter,
+  createDefaultRegistry,
+  createEvaluator,
+  OperatorEvaluator,
+  getTypedOp,
+} from './operators';
+
+// Evaluation
+export * from './evaluation';
+
+// Matching
+export * from './matching';
+
+// Resolution
+export * from './resolution';
+
+// Shapes
+export * from './shapes';
+
+// Compilers
+export * from './compilers';
+
+// Parser - human-readable expression parsing
+export {
+  parseExpression,
+  isExpressionTuple,
+  processConditionInput,
+  tokenize,
+  ParseError,
+  TokenizeError,
+  SyntaxError,
+  createDefaultOperatorTable,
+  buildOperatorTable,
+  OPERATOR_DEFINITIONS,
+  resolveAlias
+} from './parser';
+
+export type {
+  Token,
+  TokenType,
+  OperatorInfo,
+  OperatorTable
+} from './parser';
+
+// Refraction
+export * from './refraction';
+
+// Engine interface
+export * from './engine';

package/src/core/matching/activation.types.ts

@@ -0,0 +1,12 @@
+/**
+ * Core activation types - shared across all engines
+ */
+
+import { CompiledBaseRule, Fact } from '../types';
+
+export type Activation<TRule extends CompiledBaseRule = CompiledBaseRule> = {
+  rule: TRule;
+  facts: Record<string, Fact>;
+  factIds: string[];
+  matchedAt: number;
+};

package/src/core/matching/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Core matching module - shared across all engines
+ */
+
+export { Activation } from './activation.types';
+export { match, matchInputsOnly } from './matcher';

package/src/core/matching/matcher.ts

@@ -0,0 +1,127 @@
+/**
+ * Core pattern matching - shared across all engines
+ */
+
+import { CompiledBaseRule, CompiledInputParameter, BindingContext, Fact } from '../types';
+import { IWorkingMemory } from '../memory';
+import { evaluateCondition } from '../evaluation';
+import { Activation } from './activation.types';
+
+function getFactCandidates(
+  input: CompiledInputParameter,
+  context: BindingContext,
+  wm: IWorkingMemory
+): Fact[] {
+  if (input.from) {
+    const parentFact = context[input.from.param];
+    if (!parentFact) return [];
+
+    let items = parentFact.data;
+    for (const key of input.from.path) {
+      items = items?.[key];
+    }
+
+    if (!Array.isArray(items)) return [];
+
+    return items.map((item, index) => ({
+      id: `${parentFact.id}:${input.name}:${index}`,
+      type: input.type,
+      data: item
+    }));
+  }
+
+  return wm.getByType(input.type);
+}
+
+function filterByWhere(
+  facts: Fact[],
+  input: CompiledInputParameter,
+  context: BindingContext
+): Fact[] {
+  if (!input.where) return facts;
+
+  return facts.filter(fact => {
+    const localContext = { ...context, [input.name]: fact };
+    return evaluateCondition(input.where!, localContext);
+  });
+}
+
+function* generateCombinations(
+  inputs: CompiledInputParameter[],
+  wm: IWorkingMemory,
+  context: BindingContext = {},
+  index: number = 0
+): Generator<BindingContext> {
+  if (index >= inputs.length) {
+    yield context;
+    return;
+  }
+
+  const input = inputs[index];
+  const candidates = getFactCandidates(input, context, wm);
+  const filtered = filterByWhere(candidates, input, context);
+
+  for (const fact of filtered) {
+    const newContext = { ...context, [input.name]: fact };
+    yield* generateCombinations(inputs, wm, newContext, index + 1);
+  }
+}
+
+/**
+ * Match a rule against working memory and return all activations.
+ */
+export function match<TRule extends CompiledBaseRule>(
+  rule: TRule,
+  wm: IWorkingMemory
+): Activation<TRule>[] {
+  const activations: Activation<TRule>[] = [];
+  const now = Date.now();
+
+  for (const context of generateCombinations(rule.inputs, wm)) {
+    if (rule.when && !evaluateCondition(rule.when, context)) {
+      continue;
+    }
+
+    const factIds = Object.values(context)
+      .map(f => f.id)
+      .sort();
+
+    activations.push({
+      rule,
+      facts: context,
+      factIds,
+      matchedAt: now
+    });
+  }
+
+  return activations;
+}
+
+/**
+ * Match inputs only - skips 'when' clause evaluation.
+ * Used by fuzzy strategy which has its own condition evaluation
+ * that handles fuzzy operators like 'is' and 'isNot'.
+ */
+export function matchInputsOnly<TRule extends CompiledBaseRule>(
+  rule: TRule,
+  wm: IWorkingMemory
+): Activation<TRule>[] {
+  const activations: Activation<TRule>[] = [];
+  const now = Date.now();
+
+  for (const context of generateCombinations(rule.inputs, wm)) {
+    // Skip when clause - fuzzy strategy handles it
+    const factIds = Object.values(context)
+      .map(f => f.id)
+      .sort();
+
+    activations.push({
+      rule,
+      facts: context,
+      factIds,
+      matchedAt: now
+    });
+  }
+
+  return activations;
+}

package/src/core/memory/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Core memory module - shared across all engines
+ */
+
+export { IWorkingMemory } from './working-memory.interface';
+export { WorkingMemory } from './working-memory';