@higher.archi/boe 1.0.9 → 1.0.11

package/src/engines/scoring/types.ts

@@ -86,14 +86,104 @@ export type TierDefinition = {
   threshold: number | '-Infinity'; // Minimum score to qualify (inclusive), or '-Infinity' for catch-all
 };
 
+/**
+ * Style slots for tier visual presentation
+ *
+ * Each field accepts a CSS color value, class name, or any string
+ * the consumer's UI stack requires. BOE passes these through untouched.
+ *
+ * @example Tailwind classes
+ * ```typescript
+ * const style: TierStyle = {
+ *   base: 'emerald-500',
+ *   text: 'text-emerald-700',
+ *   background: 'bg-emerald-50',
+ *   border: 'border-emerald-300',
+ *   hover: 'hover:bg-emerald-100',
+ *   anchor: 'text-emerald-600 hover:text-emerald-800',
+ *   icon: 'star'
+ * };
+ * ```
+ *
+ * @example Raw CSS values
+ * ```typescript
+ * const style: TierStyle = {
+ *   base: '#10B981',
+ *   text: '#065F46',
+ *   background: '#ECFDF5',
+ *   hover: '#059669'
+ * };
+ * ```
+ */
+export type TierStyle = {
+  // Core visual
+  base?: string;           // Primary color value or class
+  text?: string;           // Text color or class
+  background?: string;     // Background color or class
+  border?: string;         // Border color or class
+
+  // Interactive states
+  hover?: string;          // Hover state color or class
+  active?: string;         // Active/pressed state color or class
+  focus?: string;          // Focus state color or class
+  disabled?: string;       // Disabled state color or class
+
+  // Links
+  anchor?: string;         // Link/anchor color or class
+
+  // Decorative
+  icon?: string;           // Icon identifier (e.g., 'star', 'shield-check')
+  badge?: string;          // Badge/pill styling
+  ring?: string;           // Ring/outline (focus rings, selection indicators)
+  shadow?: string;         // Shadow value or class
+  gradient?: string;       // Gradient value or class
+  opacity?: string;        // Opacity value or class
+
+  // Extensible
+  [key: string]: unknown;
+};
+
+/** Known keys on TierStyle that must be strings when provided */
+export const TIER_STYLE_KNOWN_KEYS: readonly string[] = [
+  'base', 'text', 'background', 'border',
+  'hover', 'active', 'focus', 'disabled',
+  'anchor',
+  'icon', 'badge', 'ring', 'shadow', 'gradient', 'opacity'
+];
+
+/**
+ * Styled extension of TierDefinition
+ *
+ * Adds an optional `style` field for visual presentation data.
+ * BOE validates the style structure at compile time but passes it
+ * through untouched — the consumer's UI layer interprets the values.
+ *
+ * Use with generics to get typed style data in scoring results:
+ * ```typescript
+ * const config: ScoringConfig<StyledTierDefinition> = {
+ *   mode: 'scoring',
+ *   strategies: ['raw'],
+ *   tiers: [
+ *     { id: 'elite', name: 'Elite', threshold: 900, style: { base: '#10B981', icon: 'star' } },
+ *     { id: 'standard', name: 'Standard', threshold: 0, style: { base: '#6B7280' } }
+ *   ]
+ * };
+ * // result.tier?.style is typed as TierStyle
+ * ```
+ */
+export type StyledTierDefinition = TierDefinition & {
+  style?: TierStyle;
+};
+
 /**
  * Matched tier in scoring result
+ *
+ * Preserves all properties from the original tier definition (including
+ * `style` when using StyledTierDefinition) with the threshold resolved
+ * to a numeric value.
  */
-export type ScoringTierMatch = {
-  id: string;
-  name?: string;
-  description?: string;
-  threshold: number;
+export type ScoringTierMatch<T extends TierDefinition = TierDefinition> = Omit<T, 'threshold'> & {
+  threshold: number;  // Resolved numeric value (never '-Infinity' string)
 };
 
 // ========================================
@@ -237,11 +327,11 @@ export type OverrideDefinition =
 /**
  * Override result — attached to ScoringResult when an override fires
  */
-export type OverrideResult = {
+export type OverrideResult<T extends TierDefinition = TierDefinition> = {
   id: string;
   effect: OverrideEffect;
   originalScore: number;
-  originalTier?: ScoringTierMatch;
+  originalTier?: ScoringTierMatch<T>;
   applied: true;
 };
 
@@ -287,25 +377,49 @@ export type ScoringRule = BaseRule & {
 /**
  * Scoring ruleset
  */
-export type ScoringRuleSet = BaseRuleSet & {
+export type ScoringRuleSet<T extends TierDefinition = TierDefinition> = BaseRuleSet & {
   mode: 'scoring';
   rules: ScoringRule[];
-  config?: Partial<ScoringConfig>;
+  config?: Partial<ScoringConfig<T>>;
+};
+
+/**
+ * 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
+ *
+ * Generic over tier type — defaults to TierDefinition for backward compatibility.
+ * Use ScoringConfig<StyledTierDefinition> to get typed style data flowing through results.
  */
-export type ScoringConfig = {
+export type ScoringConfig<T extends TierDefinition = TierDefinition> = {
   mode: 'scoring';
   strategies: ScoringMethod[];  // Default: ['raw'] - methods applied in sequence
   caps?: ScoringCaps;            // Optional global caps (used with 'capped' method)
   outputBounds?: OutputBounds;   // Optional output scaling
   baseScore?: number;            // Starting score before rule contributions (default: 0)
-  tiers?: TierDefinition[];      // Optional tier definitions for score classification
+  tiers?: T[];                   // Optional tier definitions for score classification
   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
@@ -356,10 +470,10 @@ export type CompiledOverrideDefinition =
 /**
  * Compiled scoring ruleset
  */
-export type CompiledScoringRuleSet = CompiledBaseRuleSet & {
+export type CompiledScoringRuleSet<T extends TierDefinition = TierDefinition> = CompiledBaseRuleSet & {
   mode: 'scoring';
   rules: CompiledScoringRule[];
-  config: ScoringConfig;
+  config: ScoringConfig<T>;
   overrides?: CompiledOverrideDefinition[];
 };
 
@@ -370,34 +484,61 @@ 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;
 };
 
 /**
  * Execution result
+ *
+ * Generic over tier type — when using StyledTierDefinition, the matched
+ * tier in the result preserves the full style data.
  */
-export type ScoringResult = {
+export type ScoringResult<T extends TierDefinition = TierDefinition> = {
   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)
+  tier?: ScoringTierMatch<T>;  // Matched tier (if tiers configured)
   categoryBreakdown?: CategoryResult[];  // Per-category breakdown (if categories configured)
-  override?: OverrideResult;  // Override that fired (if any)
+  override?: OverrideResult<T>;  // 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,
@@ -106,7 +110,11 @@ export type {
   ForceScoreOverride,
   OverrideResult,
   CompiledOverrideDefinition,
-  NullHandling
+  NullHandling,
+  TierDefinition,
+  TierStyle,
+  StyledTierDefinition,
+  ScoringTierMatch
 } from './engines/scoring';
 
 // Sequential