@higher.archi/boe 1.0.9 → 1.0.10

package/src/engines/fuzzy/engine.ts

@@ -51,7 +51,7 @@ export class FuzzyEngine implements IRuleEngine<CompiledFuzzyRuleSet, FuzzyOptio
   // IWorkingMemory Implementation
   // ========================================
 
-  add(input: FactInput): Fact {
+  add<T = Record<string, any>>(input: FactInput<T>): Fact<T> {
     return this.wm.add(input);
   }
 
@@ -59,7 +59,7 @@ export class FuzzyEngine implements IRuleEngine<CompiledFuzzyRuleSet, FuzzyOptio
     return this.wm.remove(factId);
   }
 
-  update(input: FactInput): Fact {
+  update<T = Record<string, any>>(input: FactInput<T>): Fact<T> {
     return this.wm.update(input);
   }
 

package/src/engines/monte-carlo/engine.ts

@@ -55,7 +55,7 @@ export class MonteCarloEngine implements IRuleEngine<CompiledMonteCarloRuleSet,
   // IWorkingMemory Implementation
   // ========================================
 
-  add(input: FactInput): Fact {
+  add<T = Record<string, any>>(input: FactInput<T>): Fact<T> {
     return this.wm.add(input);
   }
 
@@ -63,7 +63,7 @@ export class MonteCarloEngine implements IRuleEngine<CompiledMonteCarloRuleSet,
     return this.wm.remove(factId);
   }
 
-  update(input: FactInput): Fact {
+  update<T = Record<string, any>>(input: FactInput<T>): Fact<T> {
     return this.wm.update(input);
   }
 

package/src/engines/scoring/compiler.ts

@@ -216,6 +216,7 @@ export function compileScoringRuleSet(ruleSet: ScoringRuleSet): CompiledScoringR
     categories,
     overrides,
     nullHandling: ruleSet.config?.nullHandling,
+    confidenceConfig: ruleSet.config?.confidenceConfig,
     decay: ruleSet.config?.decay
   };
 

package/src/engines/scoring/engine.ts

@@ -49,7 +49,7 @@ export class ScoringEngine implements IRuleEngine<CompiledScoringRuleSet, Scorin
   // IWorkingMemory Implementation
   // ========================================
 
-  add(input: FactInput): Fact {
+  add<T = Record<string, any>>(input: FactInput<T>): Fact<T> {
     return this.wm.add(input);
   }
 
@@ -57,7 +57,7 @@ export class ScoringEngine implements IRuleEngine<CompiledScoringRuleSet, Scorin
     return this.wm.remove(factId);
   }
 
-  update(input: FactInput): Fact {
+  update<T = Record<string, any>>(input: FactInput<T>): Fact<T> {
     return this.wm.update(input);
   }
 

package/src/engines/scoring/index.ts

@@ -40,11 +40,15 @@ export {
   CompiledScoringAction,
   CompiledScoringRule,
   CompiledScoringRuleSet,
+  // Confidence types
+  ConfidenceConfig,
+  ConfidenceBreakdown,
   // Runtime types
   ScoreFunction,
   ScoreFunctionRegistry,
   ScoringOptions,
-  ScoringResult
+  ScoringResult,
+  createScoreFunction
 } from './types';
 
 // Compiler

package/src/engines/scoring/strategy.ts

@@ -26,6 +26,7 @@ import {
   ScoringTierMatch,
   OverrideResult,
   CategoryResult,
+  ConfidenceBreakdown,
   TierDefinition,
   OutputBounds
 } from './types';
@@ -257,6 +258,35 @@ export class ScoringStrategy {
       confidence = allWeight > 0 ? firedWeight / allWeight : 0;
     }
 
+    // Phase 2.8: Composite confidence (when confidenceConfig provided)
+    let confidenceBreakdown: ConfidenceBreakdown | undefined;
+
+    if (config.confidenceConfig) {
+      const scW = config.confidenceConfig.signalCoverageWeight ?? 1.0;
+      const dfW = config.confidenceConfig.dataFreshnessWeight ?? 0;
+      const totalW = scW + dfW;
+      const signalCoverage = confidence;  // from Phase 2.75
+
+      // dataFreshness = average decay multiplier across fired rules (1.0 if no decay)
+      let dataFreshness = 1.0;
+      if (fired.length > 0 && hasDecay) {
+        let sum = 0;
+        for (const ruleId of fired) {
+          sum += (decayMultipliers[ruleId] ?? 1.0);
+        }
+        dataFreshness = sum / fired.length;
+      }
+
+      if (totalW > 0) {
+        confidence = (signalCoverage * scW + dataFreshness * dfW) / totalW;
+      }
+
+      confidenceBreakdown = {
+        signalCoverage, dataFreshness,
+        weights: { signalCoverage: scW, dataFreshness: dfW }
+      };
+    }
+
     // Phase 3: Apply global strategies
     let categoryBreakdown: CategoryResult[] | undefined;
 
@@ -502,6 +532,7 @@ export class ScoringStrategy {
                 applied: true
               },
               categoryBreakdown,
+              confidenceBreakdown,
               executionTimeMs
             };
           }
@@ -570,6 +601,7 @@ export class ScoringStrategy {
       tier,
       categoryBreakdown,
       override: overrideResult,
+      confidenceBreakdown,
       ...(hasDecay ? {
         totalScoreBeforeDecay,
         contributionsBeforeDecay,

package/src/engines/scoring/types.ts

@@ -293,6 +293,26 @@ export type ScoringRuleSet = BaseRuleSet & {
   config?: Partial<ScoringConfig>;
 };
 
+/**
+ * Composite confidence configuration
+ *
+ * Controls how confidence is computed from multiple components.
+ * Without this config, confidence = signal coverage (existing behavior).
+ */
+export type ConfidenceConfig = {
+  signalCoverageWeight?: number;   // default: 1.0
+  dataFreshnessWeight?: number;    // default: 0 (existing behavior)
+};
+
+/**
+ * Breakdown of composite confidence components
+ */
+export type ConfidenceBreakdown = {
+  signalCoverage: number;
+  dataFreshness: number;
+  weights: { signalCoverage: number; dataFreshness: number };
+};
+
 /**
  * Scoring configuration
  */
@@ -306,6 +326,7 @@ 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')
+  confidenceConfig?: ConfidenceConfig;  // Optional composite confidence configuration
   decay?: {
     timestamp?: string | Expression;  // default timestamp path for all rules
     config: DecayConfig;              // engine-level decay config
@@ -370,18 +391,41 @@ export type CompiledScoringRuleSet = CompiledBaseRuleSet & {
 /**
  * Score function for dynamic scoring
  */
-export type ScoreFunction = (context: BindingContext) => number;
+export type ScoreFunction<TContext extends BindingContext = BindingContext> =
+  (context: TContext) => number;
 
 /**
  * Registry of score functions
  */
-export type ScoreFunctionRegistry = Record<string, ScoreFunction>;
+export type ScoreFunctionRegistry<TContext extends BindingContext = BindingContext> =
+  Record<string, ScoreFunction<TContext>>;
+
+/**
+ * Create a typed score function with autocomplete on context keys.
+ *
+ * Due to function contravariance, a narrowly-typed `(NarrowCtx) => number` isn't
+ * directly assignable to `(BindingContext) => number`. This helper handles the cast
+ * safely — rule inputs guarantee the correct facts at runtime.
+ *
+ * @example
+ * ```typescript
+ * type MyContext = { applicant: Fact<{ income: number; creditScore: number }> };
+ * const myFn = createScoreFunction<MyContext>((ctx) => {
+ *   return ctx.applicant.data.creditScore / 850 * 100;  // fully typed!
+ * });
+ * ```
+ */
+export function createScoreFunction<TContext extends BindingContext = BindingContext>(
+  fn: (context: TContext) => number
+): ScoreFunction {
+  return fn as ScoreFunction;
+}
 
 /**
  * Runtime options for scoring execution
  */
-export type ScoringOptions = {
-  scoreFunctions?: ScoreFunctionRegistry;  // Optional dynamic score functions
+export type ScoringOptions<TContext extends BindingContext = BindingContext> = {
+  scoreFunctions?: ScoreFunctionRegistry<TContext>;  // Optional dynamic score functions
   onFire?: (ruleId: string, context: BindingContext, score: number) => void;
 };
 
@@ -398,6 +442,7 @@ 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)
+  confidenceBreakdown?: ConfidenceBreakdown;              // composite confidence components (if confidenceConfig set)
   totalScoreBeforeDecay?: number;                        // undecayed total for comparison
   contributionsBeforeDecay?: Record<string, number>;     // undecayed per-rule contributions
   decayInfo?: Record<string, DecayInfo>;                 // per-rule decay audit

package/src/engines/sequential/engine.ts

@@ -52,7 +52,7 @@ export class SequentialEngine implements IRuleEngine<CompiledSequentialRuleSet,
   // IWorkingMemory Implementation
   // ========================================
 
-  add(input: FactInput): Fact {
+  add<T = Record<string, any>>(input: FactInput<T>): Fact<T> {
     return this.wm.add(input);
   }
 
@@ -60,7 +60,7 @@ export class SequentialEngine implements IRuleEngine<CompiledSequentialRuleSet,
     return this.wm.remove(factId);
   }
 
-  update(input: FactInput): Fact {
+  update<T = Record<string, any>>(input: FactInput<T>): Fact<T> {
     return this.wm.update(input);
   }
 

package/src/engines/utility/engine.ts

@@ -81,7 +81,7 @@ export class UtilityEngine implements IRuleEngine<CompiledUtilityRuleSet, Utilit
   // IWorkingMemory Implementation
   // ========================================
 
-  add(input: FactInput): Fact {
+  add<T = Record<string, any>>(input: FactInput<T>): Fact<T> {
     return this.wm.add(input);
   }
 
@@ -89,7 +89,7 @@ export class UtilityEngine implements IRuleEngine<CompiledUtilityRuleSet, Utilit
     return this.wm.remove(factId);
   }
 
-  update(input: FactInput): Fact {
+  update<T = Record<string, any>>(input: FactInput<T>): Fact<T> {
     return this.wm.update(input);
   }
 

package/src/index.ts

@@ -81,7 +81,8 @@ export type {
 export {
   ScoringStrategy,
   compileScoringRuleSet,
-  scoringStrategy
+  scoringStrategy,
+  createScoreFunction
 } from './engines/scoring';
 export type {
   ScoringRule,
@@ -90,11 +91,14 @@ export type {
   CompiledScoringRuleSet,
   ScoringOptions,
   ScoringResult,
+  ScoreFunction,
   ScoreFunctionRegistry,
   ScoringMethod,
   OutputBounds,
   ScoringCategory,
   CategoryResult,
+  ConfidenceConfig,
+  ConfidenceBreakdown,
   OverrideEffect,
   OverrideDefinition,
   ForceTierOverride,