@higher.archi/boe 1.0.0

package/src/engines/sequential/compiler.ts

@@ -0,0 +1,201 @@
+/**
+ * Sequential Engine Compiler
+ */
+
+import {
+  compileCondition,
+  compileOperand,
+  parsePath,
+  normalizeShape,
+  Condition,
+  PropertyRef
+} from '../../core';
+
+import {
+  SequentialRule,
+  SequentialRuleSet,
+  SequentialConfig,
+  CompiledSequentialRule,
+  CompiledSequentialRuleSet,
+  CompiledSequentialAction
+} from './types';
+
+import {
+  ThenValue,
+  ActionItem,
+  CompiledActionItem,
+  CompiledSetAction
+} from '../forward';
+
+// ========================================
+// 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)
+  };
+}
+
+function isPropertyRef(value: unknown): value is PropertyRef {
+  return typeof value === 'string' && value.startsWith('$');
+}
+
+function isExpression(value: unknown): value is Condition {
+  return Array.isArray(value) && value.length >= 2 && typeof value[0] === 'string';
+}
+
+// ========================================
+// Action Compilation
+// ========================================
+
+function compileActionItem(item: ActionItem): CompiledActionItem {
+  // Set action
+  if ('set' in item) {
+    const compiledSets: CompiledSetAction['set'] = [];
+
+    for (const [targetPath, value] of Object.entries(item.set)) {
+      if (!isPropertyRef(targetPath)) {
+        throw new Error(`Set target must be a property reference, got: ${targetPath}`);
+      }
+
+      if (isExpression(value)) {
+        compiledSets.push({
+          target: parsePath(targetPath),
+          value: { type: 'constant', value: null },
+          expr: compileCondition(value)
+        });
+      } else {
+        compiledSets.push({
+          target: parsePath(targetPath),
+          value: compileOperand(value)
+        });
+      }
+    }
+
+    return { set: compiledSets };
+  }
+
+  // Retract action
+  if ('retract' in item) {
+    const ref = item.retract;
+    if (!isPropertyRef(ref)) {
+      throw new Error(`Retract must be a property reference, got: ${ref}`);
+    }
+    const paramName = ref.slice(1).split('.')[0];
+    return { retract: paramName };
+  }
+
+  // Call action
+  if ('call' in item) {
+    return { call: item.call };
+  }
+
+  // Halt action
+  if ('halt' in item) {
+    return { halt: true };
+  }
+
+  throw new Error(`Unknown action item type: ${JSON.stringify(item)}`);
+}
+
+function normalizeThenValue(value: ThenValue): ActionItem[] {
+  if (typeof value === 'string') {
+    return [{ call: value }];
+  }
+  if (Array.isArray(value)) {
+    return value;
+  }
+  return [value];
+}
+
+function compileThenAction(thenValue: ThenValue): CompiledSequentialAction {
+  const items = normalizeThenValue(thenValue);
+  return {
+    mode: 'sequential',
+    actions: items.map(compileActionItem)
+  };
+}
+
+// ========================================
+// 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 compileSequentialRule(rule: SequentialRule, index: number = 0): CompiledSequentialRule {
+  const inputs = rule.inputs.map(compileInputParameter);
+  const when = rule.when ? compileCondition(rule.when) : undefined;
+
+  return {
+    id: rule.id,
+    name: rule.name,
+    salience: rule.salience ?? 0,
+    complexity: calculateComplexity(inputs, when),
+    index,
+    inputs,
+    when,
+    action: compileThenAction(rule.then)
+  };
+}
+
+// ========================================
+// RuleSet Compilation
+// ========================================
+
+export function compileSequentialRuleSet(ruleSet: SequentialRuleSet): CompiledSequentialRuleSet {
+  const config: SequentialConfig = {
+    mode: 'sequential',
+    strategies: ruleSet.config?.strategies ?? ['salience', 'ruleOrder']
+  };
+
+  return {
+    id: ruleSet.id,
+    name: ruleSet.name,
+    mode: 'sequential',
+    schema: ruleSet.shape ? normalizeShape(ruleSet.shape) : { type: 'object' },
+    rules: ruleSet.rules.map((rule, index) => compileSequentialRule(rule, index)),
+    config
+  };
+}

package/src/engines/sequential/engine.ts

@@ -0,0 +1,124 @@
+/**
+ * Sequential Engine
+ *
+ * Self-contained engine for sequential (first-match-wins) rule execution.
+ * Implements IRuleEngine with strongly-typed ruleset, options, and result.
+ */
+
+import {
+  IRuleEngine,
+  WorkingMemory,
+  Fact,
+  FactInput,
+  FactChange
+} from '../../core';
+
+import {
+  CompiledSequentialRuleSet,
+  SequentialOptions,
+  SequentialResult
+} from './types';
+
+import { SequentialStrategy } from './strategy';
+
+/**
+ * Sequential rule engine.
+ *
+ * Evaluates rules in order (by salience, then definition order) and fires
+ * only the first matching rule. Similar to routing or firewall rules.
+ *
+ * @example
+ * ```typescript
+ * const engine = new SequentialEngine();
+ * engine.add({ type: 'Request', data: { path: '/api/users/123', method: 'GET' } });
+ *
+ * const result = engine.execute(compiledRules, {
+ *   actions: { handleApiUsers: (ctx) => { ... } }
+ * });
+ *
+ * console.log(`Matched route: ${result.fired}`);
+ * ```
+ */
+export class SequentialEngine implements IRuleEngine<CompiledSequentialRuleSet, SequentialOptions, SequentialResult> {
+  private wm: WorkingMemory;
+  private strategy: SequentialStrategy;
+
+  constructor(workingMemory?: WorkingMemory) {
+    this.wm = workingMemory ?? new WorkingMemory();
+    this.strategy = new SequentialStrategy();
+  }
+
+  // ========================================
+  // 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 sequential ruleset.
+   *
+   * Rules are evaluated in priority order. The first matching rule fires
+   * and execution stops (first-match-wins semantics).
+   *
+   * @param ruleSet - Compiled sequential ruleset
+   * @param options - Runtime options (actions, callbacks)
+   * @returns Result with the fired rule (if any)
+   */
+  execute(ruleSet: CompiledSequentialRuleSet, options: SequentialOptions): SequentialResult {
+    return this.strategy.run(ruleSet, this.wm, options);
+  }
+
+  // ========================================
+  // Utility Methods
+  // ========================================
+
+  getWorkingMemory(): WorkingMemory {
+    return this.wm;
+  }
+}

package/src/engines/sequential/index.ts

@@ -0,0 +1,38 @@
+/**
+ * Sequential Engine
+ *
+ * Provides sequential rule execution where rules are evaluated in order
+ * and only the first matching rule executes.
+ */
+
+// Types
+export {
+  // Source types
+  SequentialRule,
+  SequentialRuleSet,
+  SequentialConfig,
+  // Compiled types
+  CompiledSequentialAction,
+  CompiledSequentialRule,
+  CompiledSequentialRuleSet,
+  // Runtime types
+  ActionHandler,
+  ActionRegistry,
+  SequentialOptions,
+  SequentialResult
+} from './types';
+
+// Compiler
+export {
+  compileSequentialRule,
+  compileSequentialRuleSet
+} from './compiler';
+
+// Strategy
+export {
+  SequentialStrategy,
+  sequentialStrategy
+} from './strategy';
+
+// Engine
+export { SequentialEngine } from './engine';

package/src/engines/sequential/strategy.ts

@@ -0,0 +1,125 @@
+/**
+ * Sequential Engine Strategy
+ *
+ * Evaluates rules in order (based on conflict resolution strategies)
+ * and executes the first matching rule only.
+ */
+
+import { match } from '../../core';
+import { IWorkingMemory } from '../../core/memory';
+
+import {
+  CompiledSequentialRuleSet,
+  CompiledSequentialRule,
+  CompiledSequentialAction,
+  SequentialOptions,
+  SequentialResult
+} from './types';
+
+// Helper to compare rules by conflict strategy
+function normalize(value: number): number {
+  if (value < 0) return -1;
+  if (value > 0) return 1;
+  return 0;
+}
+
+function compareRulesByStrategy(
+  a: CompiledSequentialRule,
+  b: CompiledSequentialRule,
+  strategy: string
+): number {
+  switch (strategy) {
+    case 'salience':
+      return normalize(b.salience - a.salience);
+
+    case 'specificity':
+      return normalize(b.inputs.length - a.inputs.length);
+
+    case 'complexity':
+      return normalize(b.complexity - a.complexity);
+
+    case 'simplicity':
+      return normalize(a.complexity - b.complexity);
+
+    case 'ruleOrder':
+      return normalize(a.index - b.index);
+
+    case 'random':
+      return normalize(Math.random() - 0.5);
+
+    // fifo/lifo don't apply to static rule sorting
+    default:
+      return 0;
+  }
+}
+
+export class SequentialStrategy {
+  run(
+    ruleSet: CompiledSequentialRuleSet,
+    wm: IWorkingMemory,
+    options: SequentialOptions
+  ): SequentialResult {
+    const startTime = performance.now();
+    const { actions, onFire } = options;
+
+    // Read config from ruleset
+    const config = ruleSet.config;
+    const strategies = config.strategies;
+
+    // Sort rules once using conflict resolution strategies
+    const sortedRules = [...ruleSet.rules].sort((a, b) => {
+      for (const strategy of strategies) {
+        const result = compareRulesByStrategy(a, b, strategy);
+        if (result !== 0) return result;
+      }
+      return 0;
+    });
+
+    // Iterate through sorted rules - first match wins
+    for (const rule of sortedRules) {
+      const activations = match(rule, wm);
+
+      // If this rule matches, fire the first activation and halt
+      if (activations.length > 0) {
+        const activation = activations[0];
+
+        // Extract actions from unified action structure
+        const ruleAction = rule.action as CompiledSequentialAction;
+
+        onFire?.(rule.id, activation.facts);
+
+        // Execute all action items
+        for (const item of ruleAction.actions) {
+          if ('call' in item) {
+            const handler = actions[item.call];
+            if (!handler) {
+              throw new Error(`Action not found: ${item.call}`);
+            }
+            handler(activation.facts, wm);
+          }
+          // Note: Sequential mode primarily uses 'call' actions
+          // Other action types (set, retract, halt) could be added here if needed
+        }
+
+        // Sequential always halts after first match
+        const executionTimeMs = Math.round((performance.now() - startTime) * 100) / 100;
+        return {
+          fired: rule.id,
+          iterations: 1,
+          executionTimeMs
+        };
+      }
+    }
+
+    // No rules matched
+    const executionTimeMs = Math.round((performance.now() - startTime) * 100) / 100;
+    return {
+      fired: null,
+      iterations: 1,
+      executionTimeMs
+    };
+  }
+}
+
+// Export a singleton instance for convenience
+export const sequentialStrategy = new SequentialStrategy();

package/src/engines/sequential/types.ts

@@ -0,0 +1,101 @@
+/**
+ * Sequential Engine Types
+ */
+
+import {
+  BaseRule,
+  BaseRuleSet,
+  CompiledBaseRule,
+  CompiledBaseRuleSet,
+  BindingContext,
+  ConflictStrategy
+} from '../../core';
+
+// Import action types from forward engine (reused)
+import {
+  ThenValue,
+  CompiledActionItem,
+  ActionHandler,
+  ActionRegistry
+} from '../forward';
+
+// ========================================
+// Source Types (User-Defined)
+// ========================================
+
+/**
+ * Sequential rule - uses 'then' for actions (same syntax as forward)
+ */
+export type SequentialRule = BaseRule & {
+  then: ThenValue;
+};
+
+/**
+ * Sequential ruleset
+ */
+export type SequentialRuleSet = BaseRuleSet & {
+  mode: 'sequential';
+  rules: SequentialRule[];
+  config?: Partial<SequentialConfig>;
+};
+
+/**
+ * Sequential configuration
+ */
+export type SequentialConfig = {
+  mode: 'sequential';
+  strategies: ConflictStrategy[];  // Default: ['salience', 'ruleOrder']
+};
+
+// ========================================
+// Compiled Types
+// ========================================
+
+/**
+ * Compiled sequential action - always normalized to array
+ */
+export type CompiledSequentialAction = {
+  mode: 'sequential';
+  actions: CompiledActionItem[];
+};
+
+/**
+ * Compiled sequential rule
+ */
+export type CompiledSequentialRule = CompiledBaseRule & {
+  action: CompiledSequentialAction;
+};
+
+/**
+ * Compiled sequential ruleset
+ */
+export type CompiledSequentialRuleSet = CompiledBaseRuleSet & {
+  mode: 'sequential';
+  rules: CompiledSequentialRule[];
+  config: SequentialConfig;
+};
+
+// ========================================
+// Runtime Types
+// ========================================
+
+// Re-export action types from forward engine
+export { ActionHandler, ActionRegistry };
+
+/**
+ * Runtime options for sequential execution
+ */
+export type SequentialOptions = {
+  actions: ActionRegistry;  // Required action handlers
+  onFire?: (ruleId: string, context: BindingContext) => void;
+};
+
+/**
+ * Sequential execution result
+ * Returns the ID of the rule that fired, or null if no rules matched
+ */
+export type SequentialResult = {
+  fired: string | null;  // ID of the rule that fired (null if none matched)
+  iterations: 1;         // Always 1 for sequential (single pass)
+  executionTimeMs: number;  // Processing time in milliseconds
+};