@jadermme/orus-core/dist/engine/prioritization.d.ts

ORUS Core Framework - Universal framework for 6 Pillars assessment, domain-agnostic

/**
 * ORUS Core - Prioritization Engine
 *
 * Pure functions for pillar prioritization and ranking.
 * Helps users understand which pillars need attention first.
 *
 * @remarks
 * All functions are:
 * - Pure (deterministic, no side effects)
 * - Domain-agnostic (work for any vertical)
 * - Configurable (custom weights and strategies)
 * - Well-documented with examples
 */
import type { PillarId } from '../types/pillar.js';
import type { PillarAssessment, SixPillarsAssessment } from '../types/assessment.js';
/**
 * Prioritization strategy
 *
 * @remarks
 * - worst_first: Prioritize pillars with lowest scores (default)
 * - best_first: Prioritize pillars with highest scores (for optimization)
 * - impact_first: Prioritize by potential impact (considers trend + confidence)
 */
export type PrioritizationStrategy = 'worst_first' | 'best_first' | 'impact_first';
/**
 * Prioritization weights configuration
 *
 * @remarks
 * Controls how much each factor influences the priority score.
 * All weights should sum to 1.0 (100%).
 *
 * Default weights:
 * - status: 0.40 (40%) - Current health state
 * - score: 0.30 (30%) - Numeric score
 * - trend: 0.20 (20%) - Direction of change
 * - confidence: 0.10 (10%) - Data reliability
 */
export interface PrioritizationWeights {
    /**
     * Weight for status (critical/attention/healthy)
     * @default 0.40
     */
    status: number;
    /**
     * Weight for numeric score (0-10)
     * @default 0.30
     */
    score: number;
    /**
     * Weight for trend (improving/stable/declining)
     * @default 0.20
     */
    trend: number;
    /**
     * Weight for confidence (low/medium/high)
     * @default 0.10
     */
    confidence: number;
}
/**
 * Pillar priority ranking
 */
export interface PillarPriority {
    /**
     * Pillar identifier
     */
    pillarId: PillarId;
    /**
     * Priority score (0-100, higher = more urgent)
     */
    priorityScore: number;
    /**
     * Rank position (1 = highest priority)
     */
    rank: number;
    /**
     * Breakdown of priority components
     */
    breakdown: {
        statusComponent: number;
        scoreComponent: number;
        trendComponent: number;
        confidenceComponent: number;
    };
}
/**
 * Prioritization result
 */
export interface PrioritizationResult {
    /**
     * Strategy used
     */
    strategy: PrioritizationStrategy;
    /**
     * Sorted ranking (index 0 = highest priority)
     */
    ranking: PillarPriority[];
    /**
     * Weights used for calculation
     */
    weights: PrioritizationWeights;
    /**
     * Timestamp of prioritization
     */
    timestamp: Date;
}
/**
 * Calculates priority score for a single pillar
 *
 * @param pillar - Pillar assessment
 * @param weights - Prioritization weights
 * @returns Priority score (0-100) and breakdown
 *
 * @remarks
 * - Pure function: deterministic calculation
 * - Higher score = higher priority
 * - Components weighted and summed
 *
 * @example
 * ```typescript
 * const pillar: PillarAssessment = {
 *   pillarId: PillarId.PILLAR_1,
 *   score: 3.0,
 *   status: 'critical',
 *   mode: 'objective',
 *   confidence: 'high',
 *   trend: 'declining',
 *   lastUpdated: new Date(),
 *   dataCompleteness: 0.9
 * };
 *
 * const result = calculatePillarPriority(pillar, DEFAULT_PRIORITIZATION_WEIGHTS);
 * // result.priorityScore will be high due to critical status + declining trend
 * ```
 */
export declare function calculatePillarPriority(pillar: PillarAssessment, weights?: PrioritizationWeights): {
    priorityScore: number;
    breakdown: PillarPriority['breakdown'];
};
/**
 * Prioritizes all pillars in an assessment
 *
 * @param params - Prioritization parameters
 * @returns Prioritization result with ranked pillars
 *
 * @remarks
 * - Pure function: deterministic ranking
 * - Default strategy: worst_first (most common use case)
 * - Custom weights allow vertical-specific prioritization
 * - Stable sort: preserves order for equal priority scores
 *
 * @example
 * ```typescript
 * const result = prioritizePillars({
 *   assessment: myAssessment,
 *   strategy: 'worst_first',
 *   weights: DEFAULT_PRIORITIZATION_WEIGHTS
 * });
 *
 * // Get top priority pillar
 * const topPriority = result.ranking[0];
 * console.log(`Focus on: ${topPriority.pillarId}`);
 * console.log(`Priority score: ${topPriority.priorityScore}`);
 *
 * // Get critical pillars only
 * const critical = result.ranking
 *   .filter(p => myAssessment.pillars[p.pillarId].status === 'critical');
 * ```
 */
export declare function prioritizePillars(params: {
    assessment: SixPillarsAssessment;
    strategy?: PrioritizationStrategy;
    weights?: PrioritizationWeights;
}): PrioritizationResult;
/**
 * Gets the top N priority pillars
 *
 * @param result - Prioritization result
 * @param count - Number of top pillars to return
 * @returns Top N pillar priorities
 *
 * @remarks
 * - Pure function: simple array slice
 * - Useful for UI display ("Top 3 priorities")
 * - Returns empty array if count <= 0
 *
 * @example
 * ```typescript
 * const result = prioritizePillars({ assessment });
 * const top3 = getTopPriorities(result, 3);
 *
 * top3.forEach(p => {
 *   console.log(`${p.rank}. ${p.pillarId} (${p.priorityScore})`);
 * });
 * ```
 */
export declare function getTopPriorities(result: PrioritizationResult, count: number): PillarPriority[];
/**
 * Gets pillars that need immediate attention
 *
 * @param result - Prioritization result
 * @param threshold - Priority score threshold (default: 70)
 * @returns Pillars above threshold
 *
 * @remarks
 * - Pure function: simple filter
 * - Default threshold 70 = urgent attention needed
 * - Empty array if no pillars meet criteria
 *
 * @example
 * ```typescript
 * const result = prioritizePillars({ assessment });
 * const urgent = getUrgentPillars(result, 75);
 *
 * if (urgent.length > 0) {
 *   console.log(`${urgent.length} pillars need urgent attention!`);
 * }
 * ```
 */
export declare function getUrgentPillars(result: PrioritizationResult, threshold?: number): PillarPriority[];
//# sourceMappingURL=prioritization.d.ts.map