import { MemoryFile } from './types.js';
import { TrustZoneName } from './trust-zones.js';
import './index-1qIcnbG1.js';

/**
 * Direct-answer retrieval tier eligibility (issue #518 slice 2).
 *
 * This module is a pure decision layer.  It takes a query, a set of
 * caller-resolved candidates (each already decorated with trust-zone,
 * taxonomy-bucket, and importance information), and the direct-answer
 * config, then returns an eligibility verdict.
 *
 * Keeping the module pure means:
 *
 * - Tests do not need a trust-zones store, taxonomy resolver, or importance
 *   scorer on disk.
 * - Slice 3 (retrieval.ts wiring) is responsible for resolving those signals
 *   before calling in; the wiring layer decides where candidates come from
 *   (entity index, token prefilter, etc.).  This module only decides
 *   whether the surfaced candidates add up to a confident direct answer.
 *
 * Not wired into retrieval yet — see slice 3.
 */

/**
 * Caller-supplied candidate.
 *
 * `trustZone`, `taxonomyBucket`, and `importanceScore` are resolved outside
 * this module because each comes from a different subsystem.  Passing them
 * as inputs keeps the function deterministic and easy to unit-test.
 *
 * `matchScore` is optional; if omitted, candidates are ranked by
 * token-overlap ratio.  Callers that already computed a better ranking
 * score (e.g. BM25, vector similarity) can supply it to drive the
 * ambiguity check.
 */
interface DirectAnswerCandidate {
    memory: MemoryFile;
    trustZone: TrustZoneName | null;
    taxonomyBucket: string | null;
    importanceScore: number;
    matchScore?: number;
}
interface DirectAnswerConfig {
    enabled: boolean;
    tokenOverlapFloor: number;
    importanceFloor: number;
    ambiguityMargin: number;
    eligibleTaxonomyBuckets: string[];
}
interface DirectAnswerInput {
    query: string;
    candidates: DirectAnswerCandidate[];
    config: DirectAnswerConfig;
    /**
     * Optional entity-ref hints resolved from the query upstream.  When
     * supplied, a candidate with a set `entityRef` must match one of these
     * (case-insensitive) to remain eligible.  Candidates without an
     * `entityRef` are allowed through regardless.
     */
    queryEntityRefs?: string[];
}
type DirectAnswerReason = "disabled" | "empty-query" | "no-candidates" | "no-eligible-candidates" | "below-token-overlap-floor" | "ambiguous" | "eligible";
interface DirectAnswerResult {
    eligible: boolean;
    reason: DirectAnswerReason;
    /** Winning candidate when eligible. */
    winner?: DirectAnswerCandidate;
    /** Computed token-overlap ratio (0..1) of the winner. */
    tokenOverlap?: number;
    /**
     * Human-readable summary suitable for
     * `RecallTierExplain.tierReason`.
     */
    narrative: string;
    /**
     * Filter labels that eliminated at least one candidate along the way.
     * Populated regardless of eligibility so the caller can surface the
     * narrowing steps in `RecallTierExplain.filteredBy`.
     */
    filteredBy: string[];
}
/** Filter labels — exported so callers and tests can match them structurally. */
declare const FILTER_LABELS: {
    readonly nonActiveStatus: "non-active-status";
    readonly notTrustedZone: "not-trusted-zone";
    readonly ineligibleTaxonomyBucket: "ineligible-taxonomy-bucket";
    readonly belowImportanceFloor: "below-importance-floor";
    readonly entityRefMismatch: "entity-ref-mismatch";
    readonly belowTokenOverlapFloor: "below-token-overlap-floor";
};
/**
 * Determine whether a query can be served by the direct-answer tier.
 *
 * Decision ladder, in order:
 *
 *   1. config.enabled === false → "disabled"
 *   2. empty query tokens → "empty-query"
 *   3. empty candidates → "no-candidates"
 *   4. hard filters drop all candidates → "no-eligible-candidates"
 *   5. token-overlap floor drops all → "below-token-overlap-floor"
 *   6. top two candidates within ambiguityMargin → "ambiguous"
 *   7. otherwise → "eligible"
 */
declare function isDirectAnswerEligible(input: DirectAnswerInput): DirectAnswerResult;

export { type DirectAnswerCandidate, type DirectAnswerConfig, type DirectAnswerInput, type DirectAnswerReason, type DirectAnswerResult, FILTER_LABELS, isDirectAnswerEligible };
