@higher.archi/boe 1.0.27 → 1.0.29

package/src/engines/decay/index.ts

@@ -0,0 +1,43 @@
+/**
+ * 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,
+  DecayIngestResult
+} 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';

package/src/engines/decay/strategy.ts

@@ -0,0 +1,433 @@
+/**
+ * Decay Engine Strategy
+ *
+ * Core execution logic for all decay strategies:
+ * - single-dimension: One temporal axis evaluated per entity
+ * - multi-dimension: Multiple temporal axes aggregated into a composite score
+ * - event-driven: Multi-dimension with re-engagement events that reset/boost/extend decay
+ */
+
+import type { IWorkingMemory, Fact } from '../../core';
+import { calculateDecayMultiplier } from '../../core/evaluation/decay';
+import type { DecayConfig, DecayInfo } from '../../core/evaluation/decay';
+
+import type {
+  CompiledDecayRuleSet,
+  CompiledSingleDimensionDecayRuleSet,
+  CompiledMultiDimensionDecayRuleSet,
+  CompiledEventDrivenDecayRuleSet,
+  CompiledDecayDimension,
+  DecayOptions,
+  DecayResult,
+  EntityDecayResult,
+  DimensionDecayResult,
+  ReEngagementEvent,
+  DecayAggregation,
+  UrgencyTier
+} from './types';
+import { resolveUrgencyTier } from './types';
+
+const MS_PER_DAY = 86_400_000;
+
+export class DecayExecutor {
+  /** Score a single entity fact directly (no WorkingMemory scan) */
+  scoreEntity(
+    fact: Fact,
+    ruleSet: CompiledDecayRuleSet,
+    asOf: Date = new Date()
+  ): EntityDecayResult {
+    const entityId = resolveEntityId(fact, ruleSet.entityIdField);
+
+    if (ruleSet.strategy === 'single-dimension') {
+      const dimResult = computeDimensionDecay(fact, ruleSet.dimension, asOf);
+      return {
+        entityId,
+        compositeFreshness: dimResult.freshnessScore,
+        urgencyTier: resolveUrgencyTier(dimResult.freshnessScore, ruleSet.urgencyThresholds),
+        dimensions: [dimResult]
+      };
+    }
+
+    // multi-dimension or event-driven (without WM-based re-engagement events)
+    const dimensions = ruleSet.strategy === 'event-driven' ? ruleSet.dimensions : ruleSet.dimensions;
+    const aggregation = ruleSet.aggregation;
+
+    const dimResults = dimensions.map(dim => computeDimensionDecay(fact, dim, asOf));
+    const compositeFreshness = aggregateFreshness(dimResults, dimensions, aggregation);
+
+    return {
+      entityId,
+      compositeFreshness,
+      urgencyTier: resolveUrgencyTier(compositeFreshness, ruleSet.urgencyThresholds),
+      dimensions: dimResults
+    };
+  }
+
+  run(
+    ruleSet: CompiledDecayRuleSet,
+    wm: IWorkingMemory,
+    options: DecayOptions = {}
+  ): DecayResult {
+    const startTime = performance.now();
+    const asOf = options.asOf ?? new Date();
+
+    let entities: EntityDecayResult[];
+
+    switch (ruleSet.strategy) {
+      case 'single-dimension':
+        entities = this.runSingleDimension(ruleSet, wm, asOf, options);
+        break;
+      case 'multi-dimension':
+        entities = this.runMultiDimension(ruleSet, wm, asOf, options);
+        break;
+      case 'event-driven':
+        entities = this.runEventDriven(ruleSet, wm, asOf, options);
+        break;
+      default:
+        throw new Error(`Unknown decay strategy: '${(ruleSet as any).strategy}'`);
+    }
+
+    const executionTimeMs = Math.round((performance.now() - startTime) * 100) / 100;
+
+    // Build tier distribution
+    const tierDistribution: Record<UrgencyTier, number> = {
+      critical: 0,
+      high: 0,
+      medium: 0,
+      low: 0,
+      stale: 0
+    };
+    for (const entity of entities) {
+      tierDistribution[entity.urgencyTier]++;
+    }
+
+    return {
+      entities,
+      totalEntities: entities.length,
+      strategy: ruleSet.strategy,
+      tierDistribution,
+      executionTimeMs
+    };
+  }
+
+  // ========================================
+  // Single-Dimension Strategy
+  // ========================================
+
+  private runSingleDimension(
+    ruleSet: CompiledSingleDimensionDecayRuleSet,
+    wm: IWorkingMemory,
+    asOf: Date,
+    options: DecayOptions
+  ): EntityDecayResult[] {
+    const entityFacts = wm.getByType(ruleSet.entityType);
+    if (entityFacts.length === 0) return [];
+
+    const results: EntityDecayResult[] = [];
+
+    for (const fact of entityFacts) {
+      const entityId = resolveEntityId(fact, ruleSet.entityIdField);
+      const dimResult = computeDimensionDecay(fact, ruleSet.dimension, asOf);
+
+      const entity: EntityDecayResult = {
+        entityId,
+        compositeFreshness: dimResult.freshnessScore,
+        urgencyTier: resolveUrgencyTier(dimResult.freshnessScore, ruleSet.urgencyThresholds),
+        dimensions: [dimResult]
+      };
+
+      if (options.onEntity) {
+        options.onEntity(entity);
+      }
+
+      results.push(entity);
+    }
+
+    return results;
+  }
+
+  // ========================================
+  // Multi-Dimension Strategy
+  // ========================================
+
+  private runMultiDimension(
+    ruleSet: CompiledMultiDimensionDecayRuleSet,
+    wm: IWorkingMemory,
+    asOf: Date,
+    options: DecayOptions
+  ): EntityDecayResult[] {
+    const entityFacts = wm.getByType(ruleSet.entityType);
+    if (entityFacts.length === 0) return [];
+
+    const results: EntityDecayResult[] = [];
+
+    for (const fact of entityFacts) {
+      const entityId = resolveEntityId(fact, ruleSet.entityIdField);
+      const dimResults = ruleSet.dimensions.map(dim =>
+        computeDimensionDecay(fact, dim, asOf)
+      );
+
+      const compositeFreshness = aggregateFreshness(
+        dimResults,
+        ruleSet.dimensions,
+        ruleSet.aggregation
+      );
+
+      const entity: EntityDecayResult = {
+        entityId,
+        compositeFreshness,
+        urgencyTier: resolveUrgencyTier(compositeFreshness, ruleSet.urgencyThresholds),
+        dimensions: dimResults
+      };
+
+      if (options.onEntity) {
+        options.onEntity(entity);
+      }
+
+      results.push(entity);
+    }
+
+    return results;
+  }
+
+  // ========================================
+  // Event-Driven Strategy
+  // ========================================
+
+  private runEventDriven(
+    ruleSet: CompiledEventDrivenDecayRuleSet,
+    wm: IWorkingMemory,
+    asOf: Date,
+    options: DecayOptions
+  ): EntityDecayResult[] {
+    const entityFacts = wm.getByType(ruleSet.entityType);
+    if (entityFacts.length === 0) return [];
+
+    const results: EntityDecayResult[] = [];
+
+    for (const fact of entityFacts) {
+      const entityId = resolveEntityId(fact, ruleSet.entityIdField);
+      const reEngagements: ReEngagementEvent[] = [];
+
+      // Build adjusted fact data by applying re-engagement rules
+      const adjustedData = { ...fact.data };
+
+      for (const rule of ruleSet.reEngagementRules) {
+        // Scan WM for events matching this rule's eventType that reference this entity
+        const events = wm.getByType(rule.eventType);
+        const matchingEvents = events.filter(e =>
+          e.data?.entityId === entityId || e.data?.targetId === entityId
+        );
+
+        if (matchingEvents.length === 0) continue;
+
+        // Use the most recent matching event
+        const latestEvent = matchingEvents.reduce((latest, e) => {
+          const latestTime = latest.data?.timestamp ? new Date(latest.data.timestamp).getTime() : 0;
+          const currentTime = e.data?.timestamp ? new Date(e.data.timestamp).getTime() : 0;
+          return currentTime > latestTime ? e : latest;
+        });
+
+        const eventTimestamp = latestEvent.data?.timestamp
+          ? new Date(latestEvent.data.timestamp).toISOString()
+          : asOf.toISOString();
+
+        // Apply effect to each dimension's timestamp field
+        for (const dim of ruleSet.dimensions) {
+          const originalTimestamp = adjustedData[dim.timestampField];
+          if (!originalTimestamp) continue;
+
+          const originalDate = new Date(originalTimestamp);
+          const config: DecayConfig = {
+            curve: dim.curve,
+            timeUnit: dim.timeUnit,
+            halfLife: dim.halfLife,
+            maxAge: dim.maxAge,
+            threshold: dim.threshold,
+            floor: dim.floor
+          };
+
+          const baseFreshness = calculateDecayMultiplier(originalDate, asOf, config).multiplier;
+
+          let adjustedFreshness = baseFreshness;
+
+          switch (rule.effect) {
+            case 'reset':
+              // Use the event timestamp instead of the original
+              adjustedData[dim.timestampField] = eventTimestamp;
+              adjustedFreshness = calculateDecayMultiplier(
+                new Date(eventTimestamp), asOf, config
+              ).multiplier;
+              break;
+
+            case 'boost':
+              // Add boost amount, clamp to 1.0
+              adjustedFreshness = Math.min(1.0, baseFreshness + (rule.boostAmount ?? 0));
+              break;
+
+            case 'extend':
+              // Push original timestamp forward by extensionDays
+              const extendedDate = new Date(
+                originalDate.getTime() + (rule.extensionDays ?? 0) * MS_PER_DAY
+              );
+              adjustedData[dim.timestampField] = extendedDate.toISOString();
+              adjustedFreshness = calculateDecayMultiplier(
+                extendedDate, asOf, config
+              ).multiplier;
+              break;
+          }
+
+          reEngagements.push({
+            ruleId: rule.id,
+            eventType: rule.eventType,
+            effect: rule.effect,
+            appliedAt: eventTimestamp,
+            freshnessBeforeBoost: baseFreshness,
+            freshnessAfterBoost: adjustedFreshness
+          });
+        }
+      }
+
+      // Compute dimension decay using adjusted data
+      const adjustedFact = { ...fact, data: adjustedData };
+      const dimResults = ruleSet.dimensions.map(dim =>
+        computeDimensionDecay(adjustedFact, dim, asOf)
+      );
+
+      // For boost effect, override freshness from re-engagement records
+      for (const reEng of reEngagements) {
+        if (reEng.effect === 'boost') {
+          // Find the matching dimension result and override its freshness
+          for (const dimResult of dimResults) {
+            // Apply the boosted freshness to the dimension
+            const originalFreshness = dimResult.freshnessScore;
+            if (originalFreshness === reEng.freshnessBeforeBoost) {
+              dimResult.freshnessScore = reEng.freshnessAfterBoost;
+              dimResult.fullyDecayed = dimResult.freshnessScore <= 0;
+            }
+          }
+        }
+      }
+
+      const compositeFreshness = aggregateFreshness(
+        dimResults,
+        ruleSet.dimensions,
+        ruleSet.aggregation
+      );
+
+      const entity: EntityDecayResult = {
+        entityId,
+        compositeFreshness,
+        urgencyTier: resolveUrgencyTier(compositeFreshness, ruleSet.urgencyThresholds),
+        dimensions: dimResults,
+        reEngagements: reEngagements.length > 0 ? reEngagements : undefined
+      };
+
+      if (options.onEntity) {
+        options.onEntity(entity);
+      }
+
+      results.push(entity);
+    }
+
+    return results;
+  }
+}
+
+// ========================================
+// Module-Level Helpers
+// ========================================
+
+function resolveEntityId(fact: Fact, entityIdField: string): string {
+  return fact.data?.[entityIdField] ?? fact.id;
+}
+
+function computeDimensionDecay(
+  fact: Fact,
+  dimension: CompiledDecayDimension,
+  asOf: Date
+): DimensionDecayResult {
+  const timestampValue = fact.data?.[dimension.timestampField];
+
+  // If no timestamp found, treat as fully decayed
+  if (timestampValue === null || timestampValue === undefined) {
+    return {
+      dimensionId: dimension.id,
+      dimensionName: dimension.name,
+      freshnessScore: dimension.floor ?? 0,
+      ageInUnits: Infinity,
+      curve: dimension.curve,
+      timestamp: '',
+      fullyDecayed: true
+    };
+  }
+
+  const dataTimestamp = new Date(timestampValue);
+  if (isNaN(dataTimestamp.getTime())) {
+    return {
+      dimensionId: dimension.id,
+      dimensionName: dimension.name,
+      freshnessScore: dimension.floor ?? 0,
+      ageInUnits: Infinity,
+      curve: dimension.curve,
+      timestamp: String(timestampValue),
+      fullyDecayed: true
+    };
+  }
+
+  const config: DecayConfig = {
+    curve: dimension.curve,
+    timeUnit: dimension.timeUnit,
+    halfLife: dimension.halfLife,
+    maxAge: dimension.maxAge,
+    threshold: dimension.threshold,
+    floor: dimension.floor
+  };
+
+  const decayInfo: DecayInfo = calculateDecayMultiplier(dataTimestamp, asOf, config);
+
+  return {
+    dimensionId: dimension.id,
+    dimensionName: dimension.name,
+    freshnessScore: decayInfo.multiplier,
+    ageInUnits: decayInfo.ageInUnits,
+    curve: decayInfo.curve,
+    timestamp: decayInfo.timestamp,
+    fullyDecayed: decayInfo.fullyDecayed
+  };
+}
+
+function aggregateFreshness(
+  dimResults: DimensionDecayResult[],
+  dimensions: CompiledDecayDimension[],
+  aggregation: DecayAggregation
+): number {
+  switch (aggregation) {
+    case 'weighted-average': {
+      let sum = 0;
+      for (let i = 0; i < dimResults.length; i++) {
+        sum += dimResults[i].freshnessScore * dimensions[i].weight;
+      }
+      return sum;
+    }
+
+    case 'minimum':
+      return Math.min(...dimResults.map(d => d.freshnessScore));
+
+    case 'geometric-mean': {
+      // Weighted geometric mean: exp(sum(weight * ln(freshness)))
+      let weightedLogSum = 0;
+      for (let i = 0; i < dimResults.length; i++) {
+        const freshness = Math.max(dimResults[i].freshnessScore, 1e-10); // avoid log(0)
+        weightedLogSum += dimensions[i].weight * Math.log(freshness);
+      }
+      return Math.exp(weightedLogSum);
+    }
+
+    default:
+      throw new Error(`Unknown aggregation: '${aggregation}'`);
+  }
+}
+
+/** Singleton instance */
+export const decayStrategy = new DecayExecutor();

package/src/engines/decay/types.ts

@@ -0,0 +1,231 @@
+/**
+ * Decay Engine Types
+ *
+ * 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.
+ */
+
+import type { DecayCurve, DecayTimeUnit } from '../../core/evaluation/decay';
+import type { SemanticPriority } from '../utility/types';
+
+// ========================================
+// Semantic Types
+// ========================================
+
+/** Decay strategy to use */
+export type DecayStrategy = 'single-dimension' | 'multi-dimension' | 'event-driven';
+
+/** Urgency tier based on freshness score */
+export type UrgencyTier = 'critical' | 'high' | 'medium' | 'low' | 'stale';
+
+/** Effect applied when a re-engagement event is detected */
+export type ReEngagementEffect = 'reset' | 'boost' | 'extend';
+
+/** Aggregation method for combining multi-dimension freshness scores */
+export type DecayAggregation = 'weighted-average' | 'minimum' | 'geometric-mean';
+
+// ========================================
+// Constants
+// ========================================
+
+/** Default urgency tier thresholds (freshness score boundaries) */
+export const URGENCY_THRESHOLDS: Record<UrgencyTier, number> = {
+  'critical': 0.8,
+  'high': 0.6,
+  'medium': 0.4,
+  'low': 0.2,
+  'stale': 0
+};
+
+// ========================================
+// Resolver Functions
+// ========================================
+
+/** Map a freshness score (0-1) to an urgency tier */
+export function resolveUrgencyTier(
+  freshness: number,
+  thresholds?: Partial<Record<UrgencyTier, number>>
+): UrgencyTier {
+  const t = { ...URGENCY_THRESHOLDS, ...thresholds };
+  if (freshness >= t.critical) return 'critical';
+  if (freshness >= t.high) return 'high';
+  if (freshness >= t.medium) return 'medium';
+  if (freshness >= t.low) return 'low';
+  return 'stale';
+}
+
+// ========================================
+// Dimension & Rule Types
+// ========================================
+
+/** A decay dimension -- a single temporal axis to evaluate */
+export type DecayDimension = {
+  id: string;
+  name?: string;
+  timestampField: string;
+  curve: DecayCurve;
+  timeUnit: DecayTimeUnit;
+  halfLife?: number;
+  maxAge?: number;
+  threshold?: number;
+  floor?: number;
+  weight: number | SemanticPriority;
+};
+
+/** Compiled dimension with resolved numeric weight */
+export type CompiledDecayDimension = {
+  id: string;
+  name?: string;
+  timestampField: string;
+  curve: DecayCurve;
+  timeUnit: DecayTimeUnit;
+  halfLife?: number;
+  maxAge?: number;
+  threshold?: number;
+  floor?: number;
+  weight: number;  // normalized to sum to 1.0
+};
+
+/** A rule that adjusts decay when a re-engagement event is detected */
+export type ReEngagementRule = {
+  id: string;
+  eventType: string;
+  effect: ReEngagementEffect;
+  boostAmount?: number;
+  extensionDays?: number;
+};
+
+// ========================================
+// Source RuleSet Types (Discriminated Union)
+// ========================================
+
+type DecayRuleSetBase = {
+  id: string;
+  name?: string;
+  mode: 'decay';
+  entityType: string;
+  entityIdField?: string;
+  urgencyThresholds?: Partial<Record<UrgencyTier, number>>;
+};
+
+/** Single-dimension strategy: one temporal axis */
+export type SingleDimensionDecayRuleSet = DecayRuleSetBase & {
+  strategy: 'single-dimension';
+  dimension: DecayDimension;
+};
+
+/** Multi-dimension strategy: multiple temporal axes aggregated together */
+export type MultiDimensionDecayRuleSet = DecayRuleSetBase & {
+  strategy: 'multi-dimension';
+  dimensions: DecayDimension[];
+  aggregation?: DecayAggregation;
+};
+
+/** Event-driven strategy: multi-dimension with re-engagement rules */
+export type EventDrivenDecayRuleSet = DecayRuleSetBase & {
+  strategy: 'event-driven';
+  dimensions: DecayDimension[];
+  aggregation?: DecayAggregation;
+  reEngagementRules: ReEngagementRule[];
+};
+
+export type DecayRuleSet =
+  | SingleDimensionDecayRuleSet
+  | MultiDimensionDecayRuleSet
+  | EventDrivenDecayRuleSet;
+
+// ========================================
+// Compiled RuleSet Types
+// ========================================
+
+type CompiledDecayRuleSetBase = {
+  id: string;
+  name?: string;
+  mode: 'decay';
+  entityType: string;
+  entityIdField: string;
+  urgencyThresholds: Record<UrgencyTier, number>;
+};
+
+export type CompiledSingleDimensionDecayRuleSet = CompiledDecayRuleSetBase & {
+  strategy: 'single-dimension';
+  dimension: CompiledDecayDimension;
+};
+
+export type CompiledMultiDimensionDecayRuleSet = CompiledDecayRuleSetBase & {
+  strategy: 'multi-dimension';
+  dimensions: CompiledDecayDimension[];
+  aggregation: DecayAggregation;
+};
+
+export type CompiledEventDrivenDecayRuleSet = CompiledDecayRuleSetBase & {
+  strategy: 'event-driven';
+  dimensions: CompiledDecayDimension[];
+  aggregation: DecayAggregation;
+  reEngagementRules: ReEngagementRule[];
+};
+
+export type CompiledDecayRuleSet =
+  | CompiledSingleDimensionDecayRuleSet
+  | CompiledMultiDimensionDecayRuleSet
+  | CompiledEventDrivenDecayRuleSet;
+
+// ========================================
+// Runtime Types
+// ========================================
+
+/** Per-dimension decay result */
+export type DimensionDecayResult = {
+  dimensionId: string;
+  dimensionName?: string;
+  freshnessScore: number;
+  ageInUnits: number;
+  curve: DecayCurve;
+  timestamp: string;
+  fullyDecayed: boolean;
+};
+
+/** Record of a re-engagement event that was applied */
+export type ReEngagementEvent = {
+  ruleId: string;
+  eventType: string;
+  effect: ReEngagementEffect;
+  appliedAt: string;
+  freshnessBeforeBoost: number;
+  freshnessAfterBoost: number;
+};
+
+/** Per-entity decay result */
+export type EntityDecayResult = {
+  entityId: string;
+  compositeFreshness: number;
+  urgencyTier: UrgencyTier;
+  dimensions: DimensionDecayResult[];
+  reEngagements?: ReEngagementEvent[];
+};
+
+/** Full decay execution result */
+export type DecayResult = {
+  entities: EntityDecayResult[];
+  totalEntities: number;
+  strategy: DecayStrategy;
+  tierDistribution: Record<UrgencyTier, number>;
+  executionTimeMs: number;
+};
+
+/** Runtime options for decay execution */
+export type DecayOptions = {
+  asOf?: Date;
+  onEntity?: (entity: EntityDecayResult) => void;
+};
+
+/** Result from ingest() -- includes individual entity result and running aggregate */
+export type DecayIngestResult = EntityDecayResult & {
+  /** Running tier distribution across all ingested entities */
+  tierDistribution: Record<UrgencyTier, number>;
+  /** Running average freshness across all ingested entities */
+  averageFreshness: number;
+  /** Total number of entities ingested so far */
+  totalIngested: number;
+};