/**
 * Literal Scorer
 *
 * Calculates multiplicative score boosts for literal matches.
 * Implements the three-source merge strategy for literal boosting.
 *
 * This is a pure domain service with no external dependencies.
 */
import type { LiteralMatch, LiteralMatchType, LiteralConfidence } from "../entities/literal";
import type { LiteralBoostWeights } from "../entities/rankingWeights";
/**
 * Scoring constants for literal boosting.
 * @deprecated Prefer {@link DEFAULT_LITERAL_BOOST_WEIGHTS} / `rankingWeights.literal` from search options.
 */
export declare const LITERAL_SCORING_CONSTANTS: LiteralBoostWeights;
/**
 * Calculate the literal multiplier for a given match type and confidence.
 *
 * @param matchType - How the chunk relates to the literal (definition/reference/import)
 * @param confidence - Detection confidence of the query literal
 * @returns Multiplier to apply to the base score
 */
export declare function calculateLiteralMultiplier(matchType: LiteralMatchType, confidence: LiteralConfidence, weights?: LiteralBoostWeights): number;
/**
 * Calculate the maximum multiplier for a set of literal matches.
 *
 * When a chunk has multiple literal matches, use the highest multiplier.
 *
 * @param matches - Array of literal matches for a chunk
 * @returns The maximum multiplier, or 1.0 if no matches
 */
export declare function calculateMaxMultiplier(matches: LiteralMatch[], weights?: LiteralBoostWeights): number;
/**
 * Result of vocabulary-based matching.
 */
export interface VocabularyMatchResult {
    /** Number of vocabulary words that matched */
    matchedWordCount: number;
    /** The vocabulary words that matched */
    matchedWords: string[];
    /** Multiplier to apply based on vocabulary match */
    multiplier: number;
    /** Whether this is a meaningful match (above threshold) */
    isSignificant: boolean;
}
/**
 * Calculate vocabulary-based scoring for a chunk.
 *
 * This is used for partial matching when no exact literal match exists.
 * E.g., query "user authentication" might match chunk with "getUserAuth" literal.
 *
 * @param queryVocabulary - Vocabulary words extracted from the query
 * @param chunkVocabulary - Vocabulary words extracted from chunk literals
 * @returns Vocabulary match result with multiplier
 */
export declare function calculateVocabularyMatch(queryVocabulary: string[], chunkVocabulary: string[], weights?: LiteralBoostWeights): VocabularyMatchResult;
/**
 * Score contribution from literal matches.
 * Used for debugging and explainability.
 */
export interface LiteralScoreContribution {
    /** The multiplier applied */
    multiplier: number;
    /** Whether this is a literal-only match (not found by semantic/BM25) */
    literalOnly: boolean;
    /** Match type of the best match */
    bestMatchType?: LiteralMatchType;
    /** Confidence of the best match */
    bestConfidence?: LiteralConfidence;
    /** Number of literal matches */
    matchCount: number;
}
/**
 * Calculate the literal score contribution for a chunk.
 *
 * @param matches - Literal matches for the chunk (may be empty)
 * @param hasSemanticOrBm25 - Whether the chunk was found by semantic or BM25 search
 * @returns Score contribution details
 */
export declare function calculateLiteralContribution(matches: LiteralMatch[], hasSemanticOrBm25: boolean, weights?: LiteralBoostWeights): LiteralScoreContribution;
/**
 * Apply literal boosting to a base score.
 *
 * Scoring rules:
 * - If chunk has both semantic/BM25 and literal match: multiply base by multiplier
 * - If chunk has only literal match: use BASE_SCORE
 * - If chunk has no literal match: use base score as-is
 *
 * @param baseScore - Score from semantic/BM25 search (0 if not found)
 * @param matches - Literal matches for the chunk
 * @param hasSemanticOrBm25 - Whether the chunk was found by semantic or BM25
 * @returns Final score after literal boosting
 */
export declare function applyLiteralBoost(baseScore: number, matches: LiteralMatch[], hasSemanticOrBm25: boolean, weights?: LiteralBoostWeights): number;
/**
 * Merge results from three search sources with literal boosting.
 *
 * @param semanticBm25Results - Results from semantic and BM25 search
 * @param literalMatches - Map from chunk ID to literal matches
 * @returns Results with literal boosting applied
 */
export interface MergeInput {
    /** Chunk ID */
    chunkId: string;
    /** Score from semantic/BM25 search */
    baseScore: number;
}
export interface MergeOutput extends MergeInput {
    /** Final score after literal boosting */
    finalScore: number;
    /** Literal contribution details */
    literalContribution: LiteralScoreContribution;
}
export declare function mergeWithLiteralBoost(semanticBm25Results: MergeInput[], literalMatchMap: Map<string, LiteralMatch[]>, weights?: LiteralBoostWeights): MergeOutput[];