@higher.archi/boe 1.0.6 → 1.0.8

package/src/engines/defeasible/strategy.ts

@@ -7,6 +7,12 @@
 
 import { match } from '../../core/matching';
 import { IWorkingMemory } from '../../core/memory';
+import {
+  calculateDecayMultiplier,
+  resolveDecayTimestamp,
+  DecayConfig,
+  DecayInfo
+} from '../../core/evaluation/decay';
 
 import {
   CompiledDefeasibleRuleSet,
@@ -101,17 +107,57 @@ export class DefeasibleStrategy {
     // Phase 1: Match all rules and collect fired rules
     const firedRules: FiredRule[] = [];
     const firedRuleIds: string[] = [];
+    const decayInfoMap: Record<string, DecayInfo> = {};
+    const decayMultipliersByRule: Record<string, number> = {};
+    const now = new Date();
 
     for (const rule of ruleSet.rules) {
       // Match inputs against working memory (includes when clause evaluation)
       const activations = match(rule, wm);
 
       for (const activation of activations) {
+        // Compute decay if configured
+        let effectiveCredibility = rule.credibility;
+        let credibilityBeforeDecay: number | undefined;
+        let ruleDecayInfo: DecayInfo | undefined;
+
+        const ruleDecay = rule.decay;
+        const engineDecay = config.decay;
+
+        if (ruleDecay || engineDecay) {
+          const tsRef = ruleDecay?.timestamp ?? (engineDecay?.timestamp as string | undefined);
+          const decayTarget = ruleDecay?.target ?? engineDecay?.target ?? 'credibility';
+
+          if (typeof tsRef === 'string') {
+            const dataTimestamp = resolveDecayTimestamp(tsRef, activation.facts);
+
+            if (dataTimestamp) {
+              const decayConfig: DecayConfig = {
+                ...(engineDecay?.config ?? { curve: 'exponential', timeUnit: 'days' }),
+                ...ruleDecay?.config
+              } as DecayConfig;
+
+              const info = calculateDecayMultiplier(dataTimestamp, now, decayConfig);
+              ruleDecayInfo = info;
+              decayInfoMap[rule.id] = info;
+              decayMultipliersByRule[rule.id] = info.multiplier;
+
+              // Apply decay to credibility if target includes it
+              if (decayTarget === 'credibility' || decayTarget === 'both') {
+                credibilityBeforeDecay = rule.credibility;
+                effectiveCredibility = rule.credibility * info.multiplier;
+              }
+            }
+          }
+        }
+
         // Rule fires
         firedRules.push({
           ruleId: rule.id,
           conclusion: rule.conclusion,
-          credibility: rule.credibility,
+          credibility: effectiveCredibility,
+          credibilityBeforeDecay,
+          decayInfo: ruleDecayInfo,
           bindings: activation.facts
         });
 
@@ -166,9 +212,21 @@ export class DefeasibleStrategy {
           if (!defeatsMap.has(defeat.rule)) {
             defeatsMap.set(defeat.rule, []);
           }
+
+          // Apply decay to defeat strength if target includes it
+          let effectiveStrength = defeat.strength;
+          const ruleDecay = rule.decay;
+          const engineDecay = config.decay;
+          const decayTarget = ruleDecay?.target ?? engineDecay?.target ?? 'credibility';
+
+          if ((decayTarget === 'defeat-strength' || decayTarget === 'both') &&
+              decayMultipliersByRule[fired.ruleId] !== undefined) {
+            effectiveStrength = defeat.strength * decayMultipliersByRule[fired.ruleId];
+          }
+
           defeatsMap.get(defeat.rule)!.push({
             by: fired.ruleId,
-            strength: defeat.strength
+            strength: effectiveStrength
           });
         }
       }
@@ -291,6 +349,7 @@ export class DefeasibleStrategy {
     };
 
     const executionTimeMs = Math.round((performance.now() - startTime) * 100) / 100;
+    const hasDecay = Object.keys(decayInfoMap).length > 0;
 
     return {
       conclusions,
@@ -300,6 +359,7 @@ export class DefeasibleStrategy {
       conflicts,
       fired: firedRuleIds,
       iterations: 1,  // Current implementation is single-pass
+      ...(hasDecay ? { decayInfo: decayInfoMap } : {}),
       executionTimeMs,
       query
     };

package/src/engines/defeasible/types.ts

@@ -20,9 +20,12 @@ import {
   CompiledBaseRule,
   CompiledBaseRuleSet,
   CompiledInputParameter,
+  Expression,
   BindingContext
 } from '../../core';
 
+import { DecayConfig, DecayInfo } from '../../core/evaluation/decay';
+
 // ========================================
 // Rule Strength Types
 // ========================================
@@ -167,6 +170,15 @@ export type DefeasibleRule = BaseRule & {
    * Useful for audit trails and explainability.
    */
   explanation?: string;
+
+  /**
+   * Temporal decay configuration for this rule
+   */
+  decay?: {
+    timestamp: string | Expression;
+    config?: Partial<DecayConfig>;
+    target?: 'credibility' | 'defeat-strength' | 'both';  // default: 'credibility'
+  };
 };
 
 /**
@@ -216,6 +228,15 @@ export type DefeasibleConfig = {
    * Maximum iterations for computing defeat cycles (default: 100)
    */
   maxIterations?: number;
+
+  /**
+   * Engine-level temporal decay configuration
+   */
+  decay?: {
+    timestamp?: string | Expression;
+    config: DecayConfig;
+    target?: 'credibility' | 'defeat-strength' | 'both';
+  };
 };
 
 /**
@@ -263,6 +284,11 @@ export type CompiledDefeasibleRule = CompiledBaseRule & {
   conclusion: CompiledConclusion | null;  // null for pure defeaters
   defeats: CompiledDefeat[];              // Normalized defeats
   specificity: number;                    // Number of conditions (for tie-breaking)
+  decay?: {
+    timestamp: string;                    // $-prefixed path
+    config?: Partial<DecayConfig>;
+    target?: 'credibility' | 'defeat-strength' | 'both';
+  };
 };
 
 /**
@@ -293,6 +319,8 @@ export type FiredRule = {
   ruleId: string;
   conclusion: CompiledConclusion | null;
   credibility: number;
+  credibilityBeforeDecay?: number;   // original credibility before decay
+  decayInfo?: DecayInfo;
   bindings: BindingContext;
 };
 
@@ -385,6 +413,11 @@ export type DefeasibleResult = {
    */
   iterations: number;
 
+  /**
+   * Per-rule decay audit trail
+   */
+  decayInfo?: Record<string, DecayInfo>;
+
   /**
    * Processing time in milliseconds
    */

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,
@@ -19,9 +25,21 @@ import {
   ScoringTierMatch,
   OverrideResult,
   CategoryResult,
-  TierDefinition
+  TierDefinition,
+  OutputBounds
 } from './types';
 
+function resolveOutputBounds(bounds: OutputBounds): { min: number; max: number } {
+  if (typeof bounds === 'object') return bounds;
+  switch (bounds) {
+    case 'percentage':  return { min: 0, max: 100 };
+    case 'points':      return { min: 0, max: 1000 };
+    case 'rating':      return { min: 0, max: 10 };
+    case 'stars':       return { min: 0, max: 5 };
+    case 'normalized':  return { min: 0, max: 1 };
+  }
+}
+
 export class ScoringStrategy {
   run(
     ruleSet: CompiledScoringRuleSet,
@@ -37,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);
 
@@ -62,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] = [];
@@ -78,10 +128,15 @@ export class ScoringStrategy {
       }
     }
 
-    // Phase 2: Normalize and accumulate
+    // Phase 2: Normalize and accumulate (only for rules that fired)
     for (const rule of ruleSet.rules) {
       const ruleAction = rule.action as CompiledScoringAction;
       const ruleRawScores = rawScores[rule.id] || [];
+
+      // Only set contributions for rules that actually fired.
+      // Unfired rules are handled in Phase 2.5 (null handling).
+      if (ruleRawScores.length === 0) continue;
+
       let accumulatedScore = 0;
 
       for (const baseScore of ruleRawScores) {
@@ -122,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)) {
@@ -285,7 +354,8 @@ export class ScoringStrategy {
       const totalWeight = Object.values(weights).reduce((sum, w) => sum + w, 0);
       if (totalWeight > 0) {
         for (const ruleId in contributions) {
-          const normalizedWeight = weights[ruleId] / totalWeight;
+          const weight = weights[ruleId] ?? 0;
+          const normalizedWeight = weight / totalWeight;
           contributions[ruleId] = contributions[ruleId] * normalizedWeight;
         }
       }
@@ -420,6 +490,7 @@ export class ScoringStrategy {
               totalScore: 0,
               confidence,
               contributions: {},
+              contributionPercentages: {},
               fired: [],
               iterations: 1,
               override: {
@@ -465,17 +536,44 @@ export class ScoringStrategy {
       }
     }
 
+    // Phase 5: Apply outputBounds — clamp totalScore to configured range
+    if (config.outputBounds) {
+      const bounds = resolveOutputBounds(config.outputBounds);
+      totalScore = Math.max(bounds.min, Math.min(bounds.max, totalScore));
+    }
+
+    // Phase 6: Compute contribution percentages
+    const contributionTotal = Object.values(contributions).reduce((sum, v) => sum + v, 0);
+    const contributionPercentages: Record<string, number> = {};
+    if (contributionTotal !== 0) {
+      for (const ruleId in contributions) {
+        contributionPercentages[ruleId] = (contributions[ruleId] / contributionTotal) * 100;
+      }
+    }
+
     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,
       contributions,
+      contributionPercentages,
       fired,
       iterations: 1,
       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>;
+  };
 };
 
 /**
@@ -378,10 +392,14 @@ export type ScoringResult = {
   totalScore: number;
   confidence: number;  // 0-1, signal coverage ratio (weighted if weights present)
   contributions: Record<string, number>;  // Which rules contributed what scores
+  contributionPercentages: Record<string, number>;  // Normalized percentages (0-100) per rule
   fired: string[];  // Rules that matched and contributed
   iterations: 1;  // Scoring is always one-pass
   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
 // ========================================