@higher.archi/boe 1.0.21 → 1.0.22

package/src/engines/ranking/types.ts

@@ -0,0 +1,231 @@
+/**
+ * Ranking Engine Types
+ *
+ * Comparative scoring engine that ranks N entities relative to each other.
+ * Supports score-based ranking, Elo ratings, and head-to-head pairwise comparison.
+ */
+
+import type {
+  CompiledScoringRuleSet,
+  ScoringOptions,
+  ScoringTierMatch,
+  TierDefinition
+} from '../scoring/types';
+import type { SemanticPriority } from '../utility/types';
+
+// ========================================
+// Semantic Types
+// ========================================
+
+/** Ranking algorithm to use */
+export type RankingStrategy = 'score' | 'elo' | 'head-to-head';
+
+/** Sort direction for rankings */
+export type RankingDirection = 'highest-first' | 'lowest-first';
+
+/** Human-readable percentile bracket */
+export type PercentileLabel =
+  | 'top-1%'
+  | 'top-5%'
+  | 'top-10%'
+  | 'top-25%'
+  | 'top-50%'
+  | 'bottom-half';
+
+/** Rank movement since previous ranking */
+export type Movement = 'climbed' | 'steady' | 'dropped';
+
+/** Elo K-factor presets controlling rating volatility */
+export type KFactorPreset = 'volatile' | 'standard' | 'stable';
+
+export const K_FACTOR_VALUES: Record<KFactorPreset, number> = {
+  'volatile': 32,    // New entities, fast adjustment
+  'standard': 16,    // Default
+  'stable': 8        // Established entities, slow drift
+};
+
+export function isKFactorPreset(value: unknown): value is KFactorPreset {
+  return typeof value === 'string' && value in K_FACTOR_VALUES;
+}
+
+// ========================================
+// Resolver Functions
+// ========================================
+
+/** Map a percentile (0-100) to a semantic label */
+export function resolvePercentileLabel(percentile: number): PercentileLabel {
+  if (percentile >= 99) return 'top-1%';
+  if (percentile >= 95) return 'top-5%';
+  if (percentile >= 90) return 'top-10%';
+  if (percentile >= 75) return 'top-25%';
+  if (percentile >= 50) return 'top-50%';
+  return 'bottom-half';
+}
+
+/** Map rank change to a semantic movement label */
+export function resolveMovement(previousRank: number, currentRank: number): Movement {
+  if (currentRank < previousRank) return 'climbed';   // lower rank number = better
+  if (currentRank > previousRank) return 'dropped';
+  return 'steady';
+}
+
+// ========================================
+// Criterion Types (Head-to-Head)
+// ========================================
+
+/** A dimension for pairwise comparison */
+export type RankingCriterion = {
+  id: string;
+  name?: string;
+  weight: number | SemanticPriority;     // 'critical', 'high', 'medium', 'low'
+  direction: RankingDirection;
+};
+
+/** Compiled criterion with resolved numeric weight */
+export type CompiledRankingCriterion = {
+  id: string;
+  name?: string;
+  weight: number;                        // normalized to sum to 1.0
+  direction: RankingDirection;
+};
+
+// ========================================
+// Strategy-Specific Config Types
+// ========================================
+
+export type ScoreRankingConfig<T extends TierDefinition = TierDefinition> = {
+  direction?: RankingDirection;          // default: 'highest-first'
+  tiers?: T[];
+};
+
+export type EloConfig = {
+  initialRating?: number;                // default: 1500
+  kFactor?: KFactorPreset | number;      // default: 'standard'
+  direction?: RankingDirection;
+};
+
+export type HeadToHeadConfig = {
+  direction?: RankingDirection;
+};
+
+// ========================================
+// Source RuleSet Types (Discriminated Union)
+// ========================================
+
+type RankingRuleSetBase = {
+  id: string;
+  name?: string;
+  mode: 'ranking';
+};
+
+/** Score strategy: point at a scoring ruleset, rank entities by totalScore */
+export type ScoreRankingRuleSet<T extends TierDefinition = TierDefinition> = RankingRuleSetBase & {
+  strategy: 'score';
+  scoringRuleset: CompiledScoringRuleSet<T>;
+  scoringOptions?: ScoringOptions;
+  entityType: string;
+  config?: ScoreRankingConfig<T>;
+};
+
+/** Elo strategy: process match history, compute ratings */
+export type EloRankingRuleSet = RankingRuleSetBase & {
+  strategy: 'elo';
+  entityType: string;
+  matchType?: string;                    // default: 'MatchResult'
+  config?: EloConfig;
+};
+
+/** Head-to-head strategy: pairwise comparison on weighted criteria */
+export type HeadToHeadRankingRuleSet = RankingRuleSetBase & {
+  strategy: 'head-to-head';
+  entityType: string;
+  criteria: RankingCriterion[];
+  config?: HeadToHeadConfig;
+};
+
+export type RankingRuleSet<T extends TierDefinition = TierDefinition> =
+  | ScoreRankingRuleSet<T>
+  | EloRankingRuleSet
+  | HeadToHeadRankingRuleSet;
+
+// ========================================
+// Compiled RuleSet Types
+// ========================================
+
+type CompiledRankingRuleSetBase = {
+  id: string;
+  name?: string;
+  mode: 'ranking';
+};
+
+export type CompiledScoreRankingRuleSet<T extends TierDefinition = TierDefinition> = CompiledRankingRuleSetBase & {
+  strategy: 'score';
+  scoringRuleset: CompiledScoringRuleSet<T>;
+  scoringOptions?: ScoringOptions;
+  entityType: string;
+  config: {
+    direction: RankingDirection;
+    tiers?: T[];
+  };
+};
+
+export type CompiledEloRankingRuleSet = CompiledRankingRuleSetBase & {
+  strategy: 'elo';
+  entityType: string;
+  matchType: string;
+  config: {
+    initialRating: number;
+    kFactor: number;
+    direction: RankingDirection;
+  };
+};
+
+export type CompiledHeadToHeadRankingRuleSet = CompiledRankingRuleSetBase & {
+  strategy: 'head-to-head';
+  entityType: string;
+  criteria: CompiledRankingCriterion[];
+  config: {
+    direction: RankingDirection;
+  };
+};
+
+export type CompiledRankingRuleSet<T extends TierDefinition = TierDefinition> =
+  | CompiledScoreRankingRuleSet<T>
+  | CompiledEloRankingRuleSet
+  | CompiledHeadToHeadRankingRuleSet;
+
+// ========================================
+// Runtime Types
+// ========================================
+
+/** Previous ranking for movement tracking */
+export type PreviousRanking = {
+  entityId: string;
+  rank: number;
+};
+
+/** Runtime options */
+export type RankingOptions = {
+  previousRankings?: PreviousRanking[];
+  onRank?: (entity: RankedEntity) => void;
+};
+
+/** Per-entity result */
+export type RankedEntity<T extends TierDefinition = TierDefinition> = {
+  entityId: string;
+  rank: number;                          // 1-based
+  score: number;
+  percentile: number;                    // 0-100
+  percentileLabel: PercentileLabel;
+  tier?: ScoringTierMatch<T>;
+  movement?: Movement;                   // only when previousRankings provided
+  delta?: number;                        // rank positions changed (positive = climbed)
+};
+
+/** Full ranking result */
+export type RankingResult<T extends TierDefinition = TierDefinition> = {
+  rankings: RankedEntity<T>[];
+  totalEntities: number;
+  strategy: RankingStrategy;
+  executionTimeMs: number;
+};

package/src/index.ts

@@ -409,6 +409,42 @@ export type {
   ExpertMemberConfig, ScoringMemberConfig
 } from './engines/ensemble';
 
+// Ranking
+export {
+  RankingEngine,
+  RankingExecutor,
+  compileRankingRuleSet,
+  rankingStrategy,
+  K_FACTOR_VALUES,
+  isKFactorPreset,
+  resolvePercentileLabel,
+  resolveMovement
+} from './engines/ranking';
+export type {
+  RankingStrategy,
+  RankingDirection,
+  PercentileLabel,
+  Movement,
+  KFactorPreset,
+  RankingCriterion,
+  CompiledRankingCriterion,
+  ScoreRankingConfig,
+  EloConfig,
+  HeadToHeadConfig,
+  ScoreRankingRuleSet,
+  EloRankingRuleSet,
+  HeadToHeadRankingRuleSet,
+  RankingRuleSet,
+  CompiledScoreRankingRuleSet,
+  CompiledEloRankingRuleSet,
+  CompiledHeadToHeadRankingRuleSet,
+  CompiledRankingRuleSet,
+  PreviousRanking,
+  RankingOptions,
+  RankedEntity,
+  RankingResult
+} from './engines/ranking';
+
 // ========================================
 // Utility Functions (from old modules, re-exported for convenience)
 // ========================================