Module evidence 

Cost-aware, answer-impact-scored evidence selection for recall.

The default recall path front-loads: it returns the top-limit records sorted by the fused retrieval score. For an LLM caller that pays per evidence chunk (context tokens), that is wasteful — most answers are decided by the first one or two strongly-relevant chunks, and the rest are dead weight.

This module adds an opt-in evidence budget that runs over the already-ranked candidate list and returns the smallest prefix that clears a configurable sufficiency bar, capped by an optional max_evidence. It is purely subtractive: it only ever returns a prefix of the input ordering, so it can never reorder or “silently lower” the retrieval’s top-k cosine ordering (see the property test in this module).

Answer-impact scoring

Relevance is computed through a pluggable EvidenceScorer trait, so callers can swap the signal used to decide sufficiency:

• CosineScorer (default) — cosine similarity of the candidate embedding against the query embedding, falling back to the retrieval score when embeddings are absent or degenerate.
• DeltaScorer — an answer-impact scorer: it scores a chunk by whether adding it to the evidence set already selected would change a downstream answer. The actual “would the answer change?” judgement is an injectable closure so the core stays model-agnostic; DeltaScorer::stub ships a deterministic marginal-novelty heuristic for tests and offline use.

Wiring

RecallRequest::evidence_budget carries the serializable EvidenceBudget config. When the config selects ScorerKind::Delta AND the engine has a scorer attached via MnemoEngine::with_evidence_scorer, that scorer is used; otherwise the path falls back to CosineScorer. The default read path (no evidence_budget) is unchanged.

Structs

BudgetSelection

Result of select_within_budget: the indices to keep (a prefix of the input order) plus diagnostics.

CosineScorer

Default scorer: cosine similarity of candidate vs query embedding.

DeltaScorer

Answer-impact scorer: scores a chunk by whether including it would change a downstream answer, relative to the evidence already selected.

EvidenceBudget

Serializable per-query evidence budget.

EvidenceCandidate

A single recall candidate handed to the scorer / budget selector.

EvidenceContext

Read-only context a scorer sees for one candidate.

EvidenceSelectionReport

Diagnostics returned alongside the trimmed evidence set.

Enums

ScorerKind

Which relevance signal the budget uses to decide sufficiency.

Traits

EvidenceScorer

Pluggable relevance signal for the evidence budget.

Functions

select_within_budget

Select the smallest prefix of candidates that satisfies budget.