@higher.archi/boe 1.0.7 → 1.0.8

package/src/engines/scoring/compiler.ts

@@ -77,7 +77,18 @@ function compileInputParameter(input: any) {
 // ========================================
 
 function compileScoringAction(action: any): CompiledScoringAction {
-  const { score, weight, normalize, reason, nullHandling } = action;
+  const { score, weight, normalize, reason, nullHandling, decay } = action;
+
+  // Compile decay timestamp if it's an expression
+  let compiledDecay: CompiledScoringAction['decay'] | undefined;
+  if (decay) {
+    compiledDecay = {
+      timestamp: Array.isArray(decay.timestamp)
+        ? compileCondition(decay.timestamp as Condition)
+        : decay.timestamp,
+      config: decay.config
+    };
+  }
 
   // Handle expression scores
   if (Array.isArray(score)) {
@@ -87,7 +98,8 @@ function compileScoringAction(action: any): CompiledScoringAction {
       weight,
       normalize,
       reason,
-      nullHandling
+      nullHandling,
+      decay: compiledDecay
     };
   }
 
@@ -98,7 +110,8 @@ function compileScoringAction(action: any): CompiledScoringAction {
     weight,
     normalize,
     reason,
-    nullHandling
+    nullHandling,
+    decay: compiledDecay
   };
 }
 
@@ -200,7 +213,8 @@ export function compileScoringRuleSet(ruleSet: ScoringRuleSet): CompiledScoringR
     tiers: ruleSet.config?.tiers,
     categories,
     overrides,
-    nullHandling: ruleSet.config?.nullHandling
+    nullHandling: ruleSet.config?.nullHandling,
+    decay: ruleSet.config?.decay
   };
 
   return {

package/src/engines/scoring/strategy.ts

@@ -10,6 +10,12 @@ import {
   evaluateCondition
 } from '../../core';
 import { IWorkingMemory } from '../../core/memory';
+import {
+  calculateDecayMultiplier,
+  resolveDecayTimestamp,
+  DecayConfig,
+  DecayInfo
+} from '../../core/evaluation/decay';
 
 import {
   CompiledScoringRuleSet,
@@ -49,8 +55,12 @@ export class ScoringStrategy {
     const weights: Record<string, number> = {};
     const fired: string[] = [];
     const rawScores: Record<string, number[]> = {}; // Track raw scores for adaptive
+    const decayInfoMap: Record<string, DecayInfo> = {};
+    const decayMultipliers: Record<string, number> = {};
 
     // Phase 1: Calculate base scores
+    const now = new Date();
+
     for (const rule of ruleSet.rules) {
       const activations = match(rule, wm);
 
@@ -74,6 +84,34 @@ export class ScoringStrategy {
           throw new Error(`Invalid score type: ${typeof ruleAction.score}`);
         }
 
+        // Apply temporal decay if configured
+        if (!decayMultipliers[rule.id]) {
+          const ruleDecay = ruleAction.decay;
+          const engineDecay = config.decay;
+
+          if (ruleDecay || engineDecay) {
+            // Resolve timestamp: rule-level overrides engine-level
+            const tsRef = ruleDecay?.timestamp ?? engineDecay?.timestamp;
+            let dataTimestamp: Date | null = null;
+
+            if (typeof tsRef === 'string') {
+              dataTimestamp = resolveDecayTimestamp(tsRef, activation.facts);
+            }
+
+            if (dataTimestamp) {
+              // Merge decay config: rule-level overrides engine-level
+              const decayConfig: DecayConfig = {
+                ...(engineDecay?.config ?? { curve: 'exponential', timeUnit: 'days' }),
+                ...ruleDecay?.config
+              } as DecayConfig;
+
+              const info = calculateDecayMultiplier(dataTimestamp, now, decayConfig);
+              decayInfoMap[rule.id] = info;
+              decayMultipliers[rule.id] = info.multiplier;
+            }
+          }
+        }
+
         // Store raw scores for adaptive strategy
         if (!rawScores[rule.id]) {
           rawScores[rule.id] = [];
@@ -139,6 +177,20 @@ export class ScoringStrategy {
       contributions[rule.id] = accumulatedScore;
     }
 
+    // Phase 2.25: Apply decay multipliers to contributions
+    const hasDecay = Object.keys(decayInfoMap).length > 0;
+    let contributionsBeforeDecay: Record<string, number> | undefined;
+
+    if (hasDecay) {
+      contributionsBeforeDecay = {};
+      for (const ruleId in contributions) {
+        contributionsBeforeDecay[ruleId] = contributions[ruleId];
+        if (decayMultipliers[ruleId] !== undefined) {
+          contributions[ruleId] *= decayMultipliers[ruleId];
+        }
+      }
+    }
+
     // Phase 2.5: Null handling — treat unfired 'zero' rules as fired with score 0
     for (const rule of ruleSet.rules) {
       if (!fired.includes(rule.id)) {
@@ -501,6 +553,12 @@ export class ScoringStrategy {
 
     const executionTimeMs = Math.round((performance.now() - startTime) * 100) / 100;
 
+    // Compute totalScoreBeforeDecay if decay was applied
+    let totalScoreBeforeDecay: number | undefined;
+    if (hasDecay && contributionsBeforeDecay) {
+      totalScoreBeforeDecay = baseScore + Object.values(contributionsBeforeDecay).reduce((sum, s) => sum + s, 0);
+    }
+
     return {
       totalScore,
       confidence,
@@ -511,6 +569,11 @@ export class ScoringStrategy {
       tier,
       categoryBreakdown,
       override: overrideResult,
+      ...(hasDecay ? {
+        totalScoreBeforeDecay,
+        contributionsBeforeDecay,
+        decayInfo: decayInfoMap
+      } : {}),
       executionTimeMs
     };
   }

package/src/engines/scoring/types.ts

@@ -13,6 +13,8 @@ import {
   BindingContext
 } from '../../core';
 
+import { DecayConfig, DecayInfo } from '../../core/evaluation/decay';
+
 // ========================================
 // Scoring Method Types
 // ========================================
@@ -268,6 +270,10 @@ export type ScoringAction = {
   normalize?: { min: number; max: number };  // Optional normalization bounds
   reason?: string;  // Optional human-readable explanation for the score
   nullHandling?: NullHandling;  // How to handle if this signal is missing (default: 'exclude')
+  decay?: {
+    timestamp: string | Expression;  // e.g. '$inspection.date'
+    config?: Partial<DecayConfig>;   // overrides engine-level defaults
+  };
 };
 
 /**
@@ -300,6 +306,10 @@ export type ScoringConfig = {
   categories?: ScoringCategory[]; // Optional category grouping for two-level weight hierarchy
   overrides?: OverrideDefinition[]; // Optional post-scoring overrides evaluated in order (first match wins)
   nullHandling?: NullHandling;  // Default null handling for all rules (default: 'exclude')
+  decay?: {
+    timestamp?: string | Expression;  // default timestamp path for all rules
+    config: DecayConfig;              // engine-level decay config
+  };
 };
 
 // ========================================
@@ -316,6 +326,10 @@ export type CompiledScoringAction = {
   normalize?: { min: number; max: number };
   reason?: string;  // Preserved from source for reporting
   nullHandling?: NullHandling;  // Preserved from source
+  decay?: {
+    timestamp: string | CompiledCondition;  // string = $path, CompiledCondition = expression
+    config?: Partial<DecayConfig>;
+  };
 };
 
 /**
@@ -384,5 +398,8 @@ export type ScoringResult = {
   tier?: ScoringTierMatch;  // Matched tier (if tiers configured)
   categoryBreakdown?: CategoryResult[];  // Per-category breakdown (if categories configured)
   override?: OverrideResult;  // Override that fired (if any)
+  totalScoreBeforeDecay?: number;                        // undecayed total for comparison
+  contributionsBeforeDecay?: Record<string, number>;     // undecayed per-rule contributions
+  decayInfo?: Record<string, DecayInfo>;                 // per-rule decay audit
   executionTimeMs: number;  // Processing time in milliseconds
 };

package/src/index.ts

@@ -375,6 +375,18 @@ export type {
 
 export { soundex, nysiis, caverphone2, cosineSimilarity } from './functions';
 
+// Temporal Decay (re-exported from core for convenience)
+export {
+  calculateDecayMultiplier,
+  resolveDecayTimestamp
+} from './core/evaluation/decay';
+export type {
+  DecayCurve,
+  DecayTimeUnit,
+  DecayConfig,
+  DecayInfo
+} from './core/evaluation/decay';
+
 // ========================================
 // QFacts - Probabilistic Fact Hydration
 // ========================================