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

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

/**
 * ORUS Core - Mode Logic
 *
 * Pure functions for handling assessment mode transitions and hybrid calculations.
 *
 * @remarks
 * ORUS supports 3 assessment modes:
 * - subjective: Quick user perception (low confidence)
 * - objective: Data-driven via domain engines (high confidence)
 * - hybrid: Combines both (medium confidence)
 *
 * This module provides:
 * - Hybrid score resolution (combining subjective + objective)
 * - Mode transition validation
 * - Confidence inference from mode
 */
import type { PillarMode, PillarConfidence } from '../types/pillar.js';
/**
 * Hybrid score calculation strategy
 *
 * @remarks
 * - weighted: Use custom weights for subjective/objective
 * - objective_priority: Favor objective data (70/30)
 * - balanced: Equal weight (50/50)
 * - subjective_priority: Favor subjective input (30/70) - rare
 */
export type HybridStrategy = 'weighted' | 'objective_priority' | 'balanced' | 'subjective_priority';
/**
 * Hybrid score calculation params
 */
export interface HybridScoreParams {
    /**
     * Subjective score from user perception
     */
    subjectiveScore: number;
    /**
     * Objective score from domain engine
     */
    objectiveScore: number;
    /**
     * Calculation strategy
     * @default 'objective_priority'
     */
    strategy?: HybridStrategy;
    /**
     * Custom weights (only used if strategy = 'weighted')
     * @default { objective: 0.7, subjective: 0.3 }
     */
    customWeights?: {
        objective: number;
        subjective: number;
    };
}
/**
 * Hybrid score calculation result
 */
export interface HybridScoreResult {
    /**
     * Resolved hybrid score
     */
    hybridScore: number;
    /**
     * Strategy used
     */
    strategy: HybridStrategy;
    /**
     * Weights applied
     */
    weights: {
        objective: number;
        subjective: number;
    };
    /**
     * Absolute difference between subjective and objective
     */
    discrepancy: number;
    /**
     * Whether discrepancy is significant (> 2 points)
     */
    hasSignificantDiscrepancy: boolean;
}
/**
 * Resolves a hybrid score from subjective and objective inputs
 *
 * @param params - Hybrid score parameters
 * @returns Hybrid score result with breakdown
 *
 * @remarks
 * - Pure function: deterministic calculation
 * - Default strategy: objective_priority (70/30)
 * - Detects significant discrepancies (> 2 points difference)
 * - Discrepancies may indicate:
 *   - User perception doesn't match data reality
 *   - Missing context in objective calculation
 *   - Need for user education or data review
 *
 * @example
 * ```typescript
 * const result = resolveHybridScore({
 *   subjectiveScore: 4.0, // User feels it's bad
 *   objectiveScore: 7.5,  // But data shows it's good
 *   strategy: 'objective_priority'
 * });
 *
 * // result.hybridScore = 6.55 (weighted toward objective)
 * // result.discrepancy = 3.5
 * // result.hasSignificantDiscrepancy = true
 * ```
 */
export declare function resolveHybridScore(params: HybridScoreParams): HybridScoreResult;
/**
 * Infers confidence level from assessment mode
 *
 * @param mode - Assessment mode
 * @returns Typical confidence level for that mode
 *
 * @remarks
 * - Pure function: simple mapping
 * - Default inference (can be overridden):
 *   - subjective => low confidence
 *   - objective => high confidence
 *   - hybrid => medium confidence
 *
 * @example
 * ```typescript
 * inferConfidenceFromMode('subjective') // => 'low'
 * inferConfidenceFromMode('objective')  // => 'high'
 * inferConfidenceFromMode('hybrid')     // => 'medium'
 * ```
 */
export declare function inferConfidenceFromMode(mode: PillarMode): PillarConfidence;
/**
 * Mode transition validation
 */
export interface ModeTransition {
    /**
     * Current mode
     */
    from: PillarMode;
    /**
     * Target mode
     */
    to: PillarMode;
}
/**
 * Mode transition validation result
 */
export interface ModeTransitionValidation {
    /**
     * Whether transition is allowed
     */
    isValid: boolean;
    /**
     * Human-readable reason
     */
    reason?: string;
    /**
     * Recommended actions if invalid
     */
    recommendations?: string[];
}
/**
 * Validates if a mode transition is allowed
 *
 * @param transition - Mode transition to validate
 * @param dataCompleteness - Current data completeness (0-1)
 * @returns Validation result
 *
 * @remarks
 * - Pure function: deterministic validation
 * - Rules:
 *   - subjective -> objective: requires dataCompleteness >= 0.7
 *   - subjective -> hybrid: requires dataCompleteness >= 0.4
 *   - objective -> hybrid: always allowed
 *   - hybrid -> objective: requires dataCompleteness >= 0.8
 *   - Same mode: always allowed (no-op)
 *   - Downgrades (objective -> subjective): always allowed but warned
 *
 * @example
 * ```typescript
 * const validation = canTransitionMode(
 *   { from: 'subjective', to: 'objective' },
 *   0.5 // Only 50% data completeness
 * );
 *
 * // validation.isValid = false
 * // validation.reason = "Insufficient data for objective mode"
 * // validation.recommendations = ["Collect more data...", ...]
 * ```
 */
export declare function canTransitionMode(transition: ModeTransition, dataCompleteness: number): ModeTransitionValidation;
/**
 * Suggests optimal mode based on data completeness
 *
 * @param dataCompleteness - Current data completeness (0-1)
 * @returns Recommended mode and reason
 *
 * @remarks
 * - Pure function: deterministic recommendation
 * - Thresholds:
 *   - < 0.4: subjective (insufficient data)
 *   - 0.4-0.7: hybrid (partial data available)
 *   - >= 0.7: objective (sufficient data)
 *
 * @example
 * ```typescript
 * suggestOptimalMode(0.3)  // => { mode: 'subjective', ... }
 * suggestOptimalMode(0.6)  // => { mode: 'hybrid', ... }
 * suggestOptimalMode(0.9)  // => { mode: 'objective', ... }
 * ```
 */
export declare function suggestOptimalMode(dataCompleteness: number): {
    mode: PillarMode;
    reason: string;
    confidence: PillarConfidence;
};
//# sourceMappingURL=modeLogic.d.ts.map