/** change: add-retrieval-match-evidence */ export declare const LEXICAL_MATCH_FIELDS: readonly ["symbol", "path", "signature", "doc", "body", "language"]; export type LexicalMatchField = (typeof LEXICAL_MATCH_FIELDS)[number]; export type MatchField = LexicalMatchField | 'vector'; export type RetrievalTier = 1 | 2 | 3; export interface MatchEvidence { field: MatchField; terms: string[]; tier: RetrievalTier; } export type SearchableFields = Partial>; export type FieldTermFrequencies = Partial>>; export declare function vectorMatchEvidence(tier: 2 | 3): MatchEvidence; /** Fail closed if a retriever violates the additive evidence contract. */ export declare function requireMatchEvidence(evidence: MatchEvidence | undefined): MatchEvidence; /** * How well the retrieval covers the question asked. * * `covered` — at least one result matched the caller's own terms, or matched on a * field that names the thing. * `weak` — results exist, but every one rests on incidental evidence: body text, a * vocabulary expansion the caller never typed, or vector proximity alone. * `uncovered` — nothing matched at all. * `partial` — the retrieval ran over material it could not read, so neither a hit list nor an * empty result can be taken at face value. Never folded from evidence alone: see * {@link resolveCoverage}. */ export type CoverageVerdict = 'covered' | 'weak' | 'uncovered' | 'partial'; /** * Fold the evidence already attached to each result into a coverage verdict. * * Derived, not tuned: no relevance threshold, no score, no configuration. Two runs * over the same index cannot disagree, and no repository needs calibrating. A * ranked list of incidental matches is shaped exactly like an answer, which is how * an agent acts on three confidently-ranked symbols that have nothing to do with * the question (spec `mcp-quality` NoFalseCoverage). */ export declare function coverageVerdict(evidence: readonly MatchEvidence[]): CoverageVerdict; /** * The kinds of question the substrate can be asked. Closed on purpose: a caller * told "not covered" needs to know WHICH question went unanswered, and an * open-ended label would drift into free-text intent guessing. */ export declare const QUESTION_KINDS: readonly ["where-is", "who-calls", "what-gates", "what-order", "is-it-tested", "why-decided"]; export type QuestionKind = (typeof QUESTION_KINDS)[number]; /** * The tool that answers each kind, or `null` where the product does not answer it * yet. `what-gates` is deliberately null: a caller asking what makes a piece of * interface appear is told the question is not served, instead of being handed a * ranked list of components (see change `add-render-guard-index`). */ export declare const QUESTION_KIND_TOOL: Readonly>; export declare function isQuestionKind(value: unknown): value is QuestionKind; /** The disclosure a `weak` or `uncovered` conclusion carries. */ export interface CoverageDisclosure { verdict: CoverageVerdict; questionKind: QuestionKind; /** The tool that answers this kind, when one exists. */ answeredBy?: string; /** Why the caller is seeing this, in one sentence. */ reason: string; } /** * Build the disclosure for a non-`covered` verdict. The wording never implies a * substitute: when no tool answers the kind, it says so. */ export declare function coverageDisclosure(verdict: CoverageVerdict, kind: QuestionKind): CoverageDisclosure; /** * Why material IN SCOPE of a retrieval could not be read. Closed on purpose, and every member * is a signal the analyzer already persisted — nothing here is recomputed at query time. * * - `parse-errors` a file parsed with tree-sitter ERROR/MISSING regions * - `parse-failed` the extractor produced no usable tree — the file contributed nothing * - `size-cap` the file exceeded a size bound and was never read * - `parse-budget` the parse was abandoned at the per-file budget * - `lossy-encoding` the source decoded lossily, so parse output may be garbage * - `grammar-unavailable` a supported language's grammar produced no graph facts at all * - `reduced-analysis` the degradation ladder shed analysis breadth under memory pressure * - `health-record-unreadable` the parse-health record is present and could not be read, so * what went unread cannot be counted — the one cause that is about the * disclosure rather than the code */ export declare const UNREADABLE_CAUSES: readonly ["parse-errors", "parse-failed", "size-cap", "parse-budget", "lossy-encoding", "grammar-unavailable", "reduced-analysis", "health-record-unreadable"]; export type UnreadableCause = (typeof UNREADABLE_CAUSES)[number]; /** * Material in scope that the index could not read, rolled up repository-wide. * * Repository-wide is the load-bearing word. The per-result parse-health boundary is scoped to * the files a conclusion SURFACED, so by construction it can never fire for the worst case — * a file that produced zero symbols never surfaces, and its absence is exactly what a confident * empty answer is built on. */ export interface ReadabilityShortfall { /** Deterministic: in {@link UNREADABLE_CAUSES} order. */ causes: UnreadableCause[]; /** Files carrying any parse-health signal. */ degradedFiles: number; /** Files excluded before or during extraction (size cap, budget, parse failure). */ excludedFiles: number; /** One sentence naming each cause with its counts. */ summary: string; } /** The coverage conclusion a retrieval handler returns. */ export interface CoverageConclusion { verdict: CoverageVerdict; questionKind: QuestionKind; answeredBy?: string; reason?: string; /** On `partial`: what the verdict would have been had everything in scope been readable. */ evidenceVerdict?: CoverageVerdict; /** On `partial`: what could not be read, and why. */ unreadable?: ReadabilityShortfall; } /** * Fold the evidence verdict together with what the retrieval could not read. * * The rule, stated once and shared by `orient` and `search_code` (spec `mcp-handlers` * RetrievalCannotClaimCoverageOverUnreadContent): * * 1. No shortfall → the evidence verdict stands, unchanged and shaped exactly as before. * 2. A shortfall → the verdict is `partial`, WHATEVER the evidence said, and the evidence * verdict travels beside it as `evidenceVerdict`. * * `covered` becomes unsayable, because a ranked list drawn from material that was only partly * read is a lower bound. `uncovered` becomes unsayable too, and that is the more expensive half: * "nothing matched" over a repository where two of three files never parsed is the confident * empty answer that makes an agent stop looking. "I found nothing" and "I could not read it" * must not render identically. * * `weak` is not preserved as the verdict either — one enum member, consistently, beats two * tools disagreeing about which obstruction wins — but nothing is lost: it travels in * `evidenceVerdict` and is restated in the reason. */ export declare function resolveCoverage(evidenceVerdict: CoverageVerdict, kind: QuestionKind, shortfall?: ReadabilityShortfall): CoverageConclusion; //# sourceMappingURL=retrieval-evidence.d.ts.map