@higher.archi/boe 1.0.0 → 1.0.2

package/src/engines/scoring/types.ts

@@ -8,6 +8,7 @@ import {
   CompiledBaseRule,
   CompiledBaseRuleSet,
   CompiledCondition,
+  Condition,
   Expression,
   BindingContext
 } from '../../core';
@@ -93,6 +94,155 @@ export type ScoringTierMatch = {
   threshold: number;
 };
 
+// ========================================
+// Category Types
+// ========================================
+
+/**
+ * Category definition for grouping related scoring signals
+ *
+ * Categories provide a two-level weight hierarchy: category weights
+ * control how much each group contributes to the total, and signal
+ * weights within each category control relative importance of rules.
+ */
+export type ScoringCategory = {
+  id: string;
+  name?: string;
+  weight: number;              // 0-1, normalized internally
+  minSignalRatio?: number;     // default 0.5 — below this, category is excluded
+};
+
+/**
+ * Per-category result breakdown showing how each category contributed
+ */
+export type CategoryResult = {
+  id: string;
+  name?: string;
+  weight: number;              // original configured weight
+  effectiveWeight: number;     // after redistribution from excluded categories
+  rawScore: number;            // weighted avg of signal scores within category
+  weightedContribution: number; // effectiveWeight × rawScore
+  signalsWithData: string[];   // rule IDs that fired
+  signalsMissing: string[];    // rule IDs that didn't fire
+  excluded: boolean;
+};
+
+// ========================================
+// Override Types
+// ========================================
+
+/**
+ * Override effect types
+ */
+export type OverrideEffect =
+  | 'force_tier'
+  | 'floor_tier'
+  | 'cap_tier'
+  | 'exclude'
+  | 'adjust_score'
+  | 'clamp_score'
+  | 'force_score';
+
+/**
+ * Base override fields shared by all effects
+ */
+type BaseOverride = {
+  id: string;
+  condition: Condition;
+};
+
+/**
+ * Force tier — override to exact tier, optionally replace score
+ */
+export type ForceTierOverride = BaseOverride & {
+  effect: 'force_tier';
+  targetTier: string;
+  score?: number;
+};
+
+/**
+ * Floor tier — set minimum tier (bump up if below)
+ */
+export type FloorTierOverride = BaseOverride & {
+  effect: 'floor_tier';
+  targetTier: string;
+};
+
+/**
+ * Cap tier — set maximum tier (cap down if above)
+ */
+export type CapTierOverride = BaseOverride & {
+  effect: 'cap_tier';
+  targetTier: string;
+};
+
+/**
+ * Exclude — nullify the entire scoring result
+ */
+export type ExcludeOverride = BaseOverride & {
+  effect: 'exclude';
+};
+
+/**
+ * Adjust score — add/subtract from total score
+ */
+export type AdjustScoreOverride = BaseOverride & {
+  effect: 'adjust_score';
+  value: number;
+};
+
+/**
+ * Clamp score — enforce floor/ceiling on the score
+ */
+export type ClampScoreOverride = BaseOverride & {
+  effect: 'clamp_score';
+  min?: number;
+  max?: number;
+};
+
+/**
+ * Force score — replace the total score entirely
+ */
+export type ForceScoreOverride = BaseOverride & {
+  effect: 'force_score';
+  score: number | Expression;
+};
+
+/**
+ * Discriminated union of all override definitions
+ *
+ * Overrides are evaluated post-scoring in order — first match wins.
+ * Each effect type has its own required fields enforced by TypeScript.
+ *
+ * @example
+ * ```typescript
+ * const overrides: OverrideDefinition[] = [
+ *   { id: 'closed-won', condition: ['equals', '$deal.stage', 'Closed Won'], effect: 'force_tier', targetTier: 'strong', score: 1000 },
+ *   { id: 'fraud-flag', condition: ['equals', '$app.fraud', true], effect: 'exclude' },
+ *   { id: 'vip-bonus', condition: ['equals', '$customer.vip', true], effect: 'adjust_score', value: 50 }
+ * ];
+ * ```
+ */
+export type OverrideDefinition =
+  | ForceTierOverride
+  | FloorTierOverride
+  | CapTierOverride
+  | ExcludeOverride
+  | AdjustScoreOverride
+  | ClampScoreOverride
+  | ForceScoreOverride;
+
+/**
+ * Override result — attached to ScoringResult when an override fires
+ */
+export type OverrideResult = {
+  id: string;
+  effect: OverrideEffect;
+  originalScore: number;
+  originalTier?: ScoringTierMatch;
+  applied: true;
+};
+
 // ========================================
 // Source Types (User-Defined)
 // ========================================
@@ -111,6 +261,7 @@ export type ScoringAction = {
  * Scoring rule - uses 'then' for scoring properties
  */
 export type ScoringRule = BaseRule & {
+  category?: string;
   then: ScoringAction;
 };
 
@@ -133,6 +284,8 @@ export type ScoringConfig = {
   outputBounds?: OutputBounds;   // Optional output scaling
   baseScore?: number;            // Starting score before rule contributions (default: 0)
   tiers?: TierDefinition[];      // 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)
 };
 
 // ========================================
@@ -154,9 +307,23 @@ export type CompiledScoringAction = {
  * Compiled scoring rule
  */
 export type CompiledScoringRule = CompiledBaseRule & {
+  category?: string;
   action: CompiledScoringAction;
 };
 
+/**
+ * Compiled override — replaces source Condition with CompiledCondition
+ * Each variant preserves its effect-specific fields
+ */
+export type CompiledOverrideDefinition =
+  | (Omit<ForceTierOverride, 'condition'> & { condition: CompiledCondition })
+  | (Omit<FloorTierOverride, 'condition'> & { condition: CompiledCondition })
+  | (Omit<CapTierOverride, 'condition'> & { condition: CompiledCondition })
+  | (Omit<ExcludeOverride, 'condition'> & { condition: CompiledCondition })
+  | (Omit<AdjustScoreOverride, 'condition'> & { condition: CompiledCondition })
+  | (Omit<ClampScoreOverride, 'condition'> & { condition: CompiledCondition })
+  | (Omit<ForceScoreOverride, 'condition'> & { condition: CompiledCondition });
+
 /**
  * Compiled scoring ruleset
  */
@@ -164,6 +331,7 @@ export type CompiledScoringRuleSet = CompiledBaseRuleSet & {
   mode: 'scoring';
   rules: CompiledScoringRule[];
   config: ScoringConfig;
+  overrides?: CompiledOverrideDefinition[];
 };
 
 // ========================================
@@ -197,5 +365,7 @@ export type ScoringResult = {
   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)
   executionTimeMs: number;  // Processing time in milliseconds
 };

package/src/index.ts

@@ -92,7 +92,20 @@ export type {
   ScoringResult,
   ScoreFunctionRegistry,
   ScoringMethod,
-  OutputBounds
+  OutputBounds,
+  ScoringCategory,
+  CategoryResult,
+  OverrideEffect,
+  OverrideDefinition,
+  ForceTierOverride,
+  FloorTierOverride,
+  CapTierOverride,
+  ExcludeOverride,
+  AdjustScoreOverride,
+  ClampScoreOverride,
+  ForceScoreOverride,
+  OverrideResult,
+  CompiledOverrideDefinition
 } from './engines/scoring';
 
 // Sequential