@higher.archi/boe 1.0.26 → 1.0.28

package/src/engines/decay/compiler.ts

@@ -0,0 +1,276 @@
+/**
+ * Decay Engine Compiler
+ *
+ * Validates decay rulesets and resolves defaults.
+ */
+
+import { CompilationError } from '../../core/errors';
+import { SEMANTIC_PRIORITY_VALUES, isSemanticPriority, type SemanticPriority } from '../utility/types';
+
+import type {
+  DecayRuleSet,
+  CompiledDecayRuleSet,
+  CompiledSingleDimensionDecayRuleSet,
+  CompiledMultiDimensionDecayRuleSet,
+  CompiledEventDrivenDecayRuleSet,
+  CompiledDecayDimension,
+  DecayDimension,
+  ReEngagementRule,
+  UrgencyTier
+} from './types';
+import { URGENCY_THRESHOLDS } from './types';
+
+/**
+ * Compile and validate a decay ruleset.
+ */
+export function compileDecayRuleSet(
+  ruleSet: DecayRuleSet
+): CompiledDecayRuleSet {
+  if (!ruleSet.id) {
+    throw new CompilationError('Decay ruleset requires an id');
+  }
+
+  if (ruleSet.mode !== 'decay') {
+    throw new CompilationError(`Expected mode 'decay', got '${ruleSet.mode}'`);
+  }
+
+  if (!ruleSet.entityType || ruleSet.entityType.trim() === '') {
+    throw new CompilationError('entityType is required and must be non-empty');
+  }
+
+  const entityIdField = ruleSet.entityIdField ?? 'id';
+  const urgencyThresholds = resolveUrgencyThresholds(ruleSet.urgencyThresholds);
+
+  switch (ruleSet.strategy) {
+    case 'single-dimension':
+      return compileSingleDimension(ruleSet, entityIdField, urgencyThresholds);
+    case 'multi-dimension':
+      return compileMultiDimension(ruleSet, entityIdField, urgencyThresholds);
+    case 'event-driven':
+      return compileEventDriven(ruleSet, entityIdField, urgencyThresholds);
+    default:
+      throw new CompilationError(`Unknown decay strategy: '${(ruleSet as any).strategy}'`);
+  }
+}
+
+// ========================================
+// Strategy-Specific Compilers
+// ========================================
+
+function compileSingleDimension(
+  ruleSet: DecayRuleSet & { strategy: 'single-dimension' },
+  entityIdField: string,
+  urgencyThresholds: Record<UrgencyTier, number>
+): CompiledSingleDimensionDecayRuleSet {
+  const dimension = ruleSet.dimension;
+  if (!dimension) {
+    throw new CompilationError('Single-dimension strategy requires a dimension');
+  }
+
+  validateDimension(dimension);
+
+  return {
+    id: ruleSet.id,
+    name: ruleSet.name,
+    mode: 'decay',
+    strategy: 'single-dimension',
+    entityType: ruleSet.entityType,
+    entityIdField,
+    urgencyThresholds,
+    dimension: compileDimension(dimension, 1.0)
+  };
+}
+
+function compileMultiDimension(
+  ruleSet: DecayRuleSet & { strategy: 'multi-dimension' },
+  entityIdField: string,
+  urgencyThresholds: Record<UrgencyTier, number>
+): CompiledMultiDimensionDecayRuleSet {
+  const { dimensions } = ruleSet;
+
+  if (!dimensions || !Array.isArray(dimensions) || dimensions.length === 0) {
+    throw new CompilationError('Multi-dimension strategy requires at least one dimension');
+  }
+
+  validateDimensionIds(dimensions);
+  for (const dim of dimensions) {
+    validateDimension(dim);
+  }
+
+  const compiledDimensions = compileDimensions(dimensions);
+
+  return {
+    id: ruleSet.id,
+    name: ruleSet.name,
+    mode: 'decay',
+    strategy: 'multi-dimension',
+    entityType: ruleSet.entityType,
+    entityIdField,
+    urgencyThresholds,
+    dimensions: compiledDimensions,
+    aggregation: ruleSet.aggregation ?? 'weighted-average'
+  };
+}
+
+function compileEventDriven(
+  ruleSet: DecayRuleSet & { strategy: 'event-driven' },
+  entityIdField: string,
+  urgencyThresholds: Record<UrgencyTier, number>
+): CompiledEventDrivenDecayRuleSet {
+  const { dimensions, reEngagementRules } = ruleSet;
+
+  if (!dimensions || !Array.isArray(dimensions) || dimensions.length === 0) {
+    throw new CompilationError('Event-driven strategy requires at least one dimension');
+  }
+
+  validateDimensionIds(dimensions);
+  for (const dim of dimensions) {
+    validateDimension(dim);
+  }
+
+  if (!reEngagementRules || !Array.isArray(reEngagementRules) || reEngagementRules.length === 0) {
+    throw new CompilationError('Event-driven strategy requires at least one re-engagement rule');
+  }
+
+  validateReEngagementRules(reEngagementRules);
+
+  const compiledDimensions = compileDimensions(dimensions);
+
+  return {
+    id: ruleSet.id,
+    name: ruleSet.name,
+    mode: 'decay',
+    strategy: 'event-driven',
+    entityType: ruleSet.entityType,
+    entityIdField,
+    urgencyThresholds,
+    dimensions: compiledDimensions,
+    aggregation: ruleSet.aggregation ?? 'weighted-average',
+    reEngagementRules
+  };
+}
+
+// ========================================
+// Validation Helpers
+// ========================================
+
+function validateDimension(dim: DecayDimension): void {
+  if (!dim.id) {
+    throw new CompilationError('Each dimension requires an id');
+  }
+
+  if (!dim.timestampField) {
+    throw new CompilationError(`Dimension '${dim.id}' requires a timestampField`);
+  }
+
+  switch (dim.curve) {
+    case 'exponential':
+      if (dim.halfLife === undefined || dim.halfLife <= 0) {
+        throw new CompilationError(`Dimension '${dim.id}' with exponential curve requires a positive halfLife`);
+      }
+      break;
+    case 'linear':
+      if (dim.maxAge === undefined || dim.maxAge <= 0) {
+        throw new CompilationError(`Dimension '${dim.id}' with linear curve requires a positive maxAge`);
+      }
+      break;
+    case 'step':
+      if (dim.threshold === undefined || dim.threshold <= 0) {
+        throw new CompilationError(`Dimension '${dim.id}' with step curve requires a positive threshold`);
+      }
+      break;
+    default:
+      throw new CompilationError(`Dimension '${dim.id}' has unknown curve: '${dim.curve}'`);
+  }
+}
+
+function validateDimensionIds(dimensions: DecayDimension[]): void {
+  const ids = new Set<string>();
+  for (const dim of dimensions) {
+    if (!dim.id) {
+      throw new CompilationError('Each dimension requires an id');
+    }
+    if (ids.has(dim.id)) {
+      throw new CompilationError(`Duplicate dimension id: '${dim.id}'`);
+    }
+    ids.add(dim.id);
+  }
+}
+
+function validateReEngagementRules(rules: ReEngagementRule[]): void {
+  const ids = new Set<string>();
+  for (const rule of rules) {
+    if (!rule.id) {
+      throw new CompilationError('Each re-engagement rule requires an id');
+    }
+    if (ids.has(rule.id)) {
+      throw new CompilationError(`Duplicate re-engagement rule id: '${rule.id}'`);
+    }
+    ids.add(rule.id);
+
+    if (!rule.eventType || rule.eventType.trim() === '') {
+      throw new CompilationError(`Re-engagement rule '${rule.id}' requires a non-empty eventType`);
+    }
+
+    const validEffects = ['reset', 'boost', 'extend'];
+    if (!validEffects.includes(rule.effect)) {
+      throw new CompilationError(`Re-engagement rule '${rule.id}' has invalid effect: '${rule.effect}'`);
+    }
+
+    if (rule.effect === 'boost' && (rule.boostAmount === undefined || rule.boostAmount <= 0)) {
+      throw new CompilationError(`Re-engagement rule '${rule.id}' with boost effect requires a positive boostAmount`);
+    }
+
+    if (rule.effect === 'extend' && (rule.extensionDays === undefined || rule.extensionDays <= 0)) {
+      throw new CompilationError(`Re-engagement rule '${rule.id}' with extend effect requires a positive extensionDays`);
+    }
+  }
+}
+
+// ========================================
+// Compilation Helpers
+// ========================================
+
+function compileDimension(dim: DecayDimension, weight: number): CompiledDecayDimension {
+  return {
+    id: dim.id,
+    name: dim.name,
+    timestampField: dim.timestampField,
+    curve: dim.curve,
+    timeUnit: dim.timeUnit,
+    halfLife: dim.halfLife,
+    maxAge: dim.maxAge,
+    threshold: dim.threshold,
+    floor: dim.floor,
+    weight
+  };
+}
+
+function compileDimensions(dimensions: DecayDimension[]): CompiledDecayDimension[] {
+  // Resolve semantic weights to numeric
+  const resolved: { dim: DecayDimension; weight: number }[] = dimensions.map(dim => {
+    let weight: number;
+    if (isSemanticPriority(dim.weight)) {
+      weight = SEMANTIC_PRIORITY_VALUES[dim.weight as SemanticPriority];
+    } else if (typeof dim.weight === 'number') {
+      weight = dim.weight;
+    } else {
+      throw new CompilationError(`Invalid weight for dimension '${dim.id}': '${dim.weight}'`);
+    }
+    return { dim, weight };
+  });
+
+  // Normalize weights to sum to 1.0
+  const totalWeight = resolved.reduce((sum, r) => sum + r.weight, 0);
+  if (totalWeight === 0) {
+    throw new CompilationError('Dimension weights must not all be zero');
+  }
+
+  return resolved.map(r => compileDimension(r.dim, r.weight / totalWeight));
+}
+
+function resolveUrgencyThresholds(
+  overrides?: Partial<Record<UrgencyTier, number>>
+): Record<UrgencyTier, number> {
+  return { ...URGENCY_THRESHOLDS, ...overrides };
+}

package/src/engines/decay/engine.ts

@@ -0,0 +1,119 @@
+/**
+ * Decay Engine
+ *
+ * Temporal decay engine that computes freshness scores for entities based
+ * on how recently their data was updated. Supports single-dimension,
+ * multi-dimension, and event-driven decay strategies.
+ *
+ * @example
+ * ```typescript
+ * const engine = new DecayEngine();
+ * engine.add({ type: 'Lead', data: { id: 'l1', lastContact: '2024-01-15' } });
+ * engine.add({ type: 'Lead', data: { id: 'l2', lastContact: '2024-03-01' } });
+ *
+ * const result = engine.execute(compiledDecay);
+ * console.log(result.entities[0]); // { entityId: 'l1', compositeFreshness: 0.42, urgencyTier: 'medium', ... }
+ * ```
+ */
+
+import {
+  WorkingMemory,
+  Fact,
+  FactInput,
+  FactChange
+} from '../../core';
+
+import type {
+  CompiledDecayRuleSet,
+  DecayOptions,
+  DecayResult
+} from './types';
+
+import { DecayExecutor } from './strategy';
+
+export class DecayEngine {
+  private wm: WorkingMemory;
+  private strategy: DecayExecutor;
+
+  constructor(workingMemory?: WorkingMemory) {
+    this.wm = workingMemory ?? new WorkingMemory();
+    this.strategy = new DecayExecutor();
+  }
+
+  // ========================================
+  // IWorkingMemory Implementation
+  // ========================================
+
+  add<T = Record<string, any>>(input: FactInput<T>): Fact<T> {
+    return this.wm.add(input);
+  }
+
+  remove(factId: string): Fact | undefined {
+    return this.wm.remove(factId);
+  }
+
+  update<T = Record<string, any>>(input: FactInput<T>): Fact<T> {
+    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();
+  }
+
+  // ========================================
+  // Engine Execution
+  // ========================================
+
+  /**
+   * Execute a decay ruleset.
+   *
+   * Computes freshness scores for all entities of the configured type
+   * and maps each to an urgency tier.
+   *
+   * @param ruleSet - Compiled decay ruleset
+   * @param options - Runtime options (asOf date, onEntity callback)
+   * @returns Decay result with per-entity freshness and tier distribution
+   */
+  execute(
+    ruleSet: CompiledDecayRuleSet,
+    options: DecayOptions = {}
+  ): DecayResult {
+    return this.strategy.run(ruleSet, this.wm, options);
+  }
+
+  // ========================================
+  // Utility Methods
+  // ========================================
+
+  getWorkingMemory(): WorkingMemory {
+    return this.wm;
+  }
+}

package/src/engines/decay/index.ts

@@ -0,0 +1,42 @@
+/**
+ * Decay Engine -- Temporal Freshness Scoring
+ */
+
+// Types
+export type {
+  DecayStrategy,
+  UrgencyTier,
+  ReEngagementEffect,
+  DecayAggregation,
+  DecayDimension,
+  CompiledDecayDimension,
+  ReEngagementRule,
+  SingleDimensionDecayRuleSet,
+  MultiDimensionDecayRuleSet,
+  EventDrivenDecayRuleSet,
+  DecayRuleSet,
+  CompiledSingleDimensionDecayRuleSet,
+  CompiledMultiDimensionDecayRuleSet,
+  CompiledEventDrivenDecayRuleSet,
+  CompiledDecayRuleSet,
+  DimensionDecayResult,
+  ReEngagementEvent,
+  EntityDecayResult,
+  DecayResult,
+  DecayOptions
+} from './types';
+
+// Constants & utilities
+export {
+  URGENCY_THRESHOLDS,
+  resolveUrgencyTier
+} from './types';
+
+// Compiler
+export { compileDecayRuleSet } from './compiler';
+
+// Strategy
+export { DecayExecutor, decayStrategy } from './strategy';
+
+// Engine
+export { DecayEngine } from './engine';