agenr 2.0.0 → 2.1.0

package/dist/core/recall/index.d.ts

@@ -1,109 +1,5 @@
-import { E as Expiry, a as EntryType, R as RecallInput, b as RecallPorts, c as RecallOutput } from '../../ports-D2NOK2gR.js';
-export { d as EntryFilters, F as FtsCandidate, H as HistoricalPredecessorLookupParams, e as RecallCandidateEntry, f as RecallRankingProfile, V as VectorCandidate } from '../../ports-D2NOK2gR.js';
-
-/**
- * Backend-agnostic lexical search tier used to plan adapter queries.
- */
-type LexicalSearchTier = {
-    tier: "exact";
-    text: string;
-} | {
-    tier: "all_tokens" | "any_tokens";
-    tokens: string[];
-};
-/**
- * Tokenize free-form text into normalized lexical terms.
- *
- * @param text - Source text to tokenize.
- * @returns Lowercased non-stopword tokens.
- */
-declare function tokenize(text: string): string[];
-/**
- * Build a lexical search plan from raw user text.
- *
- * @param text - Raw query text.
- * @returns Exact, all-token, and any-token tiers in cascade order.
- */
-declare function buildLexicalPlan(text: string): LexicalSearchTier[];
-/**
- * Compute the lexical overlap score between a query and an entry.
- *
- * @param query - Raw recall query text.
- * @param subject - Entry subject text.
- * @param content - Entry content text.
- * @returns Normalized lexical overlap signal in the 0-1 range.
- */
-declare function computeLexicalScore(query: string, subject: string, content: string): number;
-
-/**
- * Score breakdown returned for a ranked recall candidate.
- */
-interface CandidateScore {
-    score: number;
-    scores: {
-        relevance: number;
-        vector: number;
-        lexical: number;
-        recency: number;
-        importance: number;
-    };
-}
-/**
- * Compute the tier-aware half-life recency score for an entry.
- *
- * @param createdAt - Entry creation timestamp.
- * @param expiry - Entry durability tier.
- * @param now - Reference time for the age calculation.
- * @returns Normalized recency score in the 0-1 range.
- */
-declare function recencyScore(createdAt: Date | string, expiry: Expiry, now?: Date): number;
-/**
- * Compute a gaussian recency score centered on an around-date query anchor.
- *
- * @param createdAt - Entry creation timestamp.
- * @param aroundDate - Temporal anchor inferred or provided by the user.
- * @param radiusDays - Standard deviation-like radius in days.
- * @returns Normalized temporal proximity score in the 0-1 range.
- */
-declare function gaussianRecency(createdAt: Date | string, aroundDate: Date, radiusDays: number): number;
-/**
- * Normalize an importance value from the 1-10 domain into the 0.4-1.0 score range.
- *
- * @param importance - Raw entry importance.
- * @returns Normalized importance score in the 0-1 range.
- */
-declare function importanceScore(importance: number): number;
-/**
- * Combine vector and lexical relevance signals into a single query-relevance score.
- *
- * @param vectorSim - Vector similarity score.
- * @param lexical - Lexical overlap score.
- * @returns Combined relevance score in the 0-1 range.
- */
-declare function combinedRelevance(vectorSim: number, lexical: number): number;
-/**
- * Compute the final recall score and its component breakdown for a candidate.
- *
- * @param params - Candidate signal inputs.
- * @returns Final score plus signal breakdown.
- */
-declare function scoreCandidate(params: {
-    vectorSim: number;
-    lexical: number;
-    recency: number;
-    importance: number;
-}): CandidateScore;
-/**
- * Compute cosine similarity between two numeric vectors.
- *
- * Non-finite coordinates are treated as zero and negative similarities are clamped
- * to zero because recall scoring only consumes a 0-1 signal.
- *
- * @param left - Left-hand vector.
- * @param right - Right-hand vector.
- * @returns Cosine similarity in the 0-1 range.
- */
-declare function cosineSimilarity(left: number[], right: number[]): number;
+import { E as EntryType, C as CrossEncoderPort, a as Expiry, R as RecallInput, b as RecallPorts, c as RecallOutput } from '../../ports-Nj5nd2Ri.js';
+export { D as DEFAULT_NEIGHBORHOOD_BUDGET, d as DEFAULT_SEEDED_RERANK_WEIGHT, e as DEFAULT_STRONG_SEED_SCORE_GAP, f as DEFAULT_STRONG_SEED_TOP_N, g as EntityAttributeKind, h as EntityAttributeQueryShape, i as EntryFilters, j as EntryNeighborhoodRequest, F as FtsCandidate, N as NeighborhoodFamily, k as RecallCandidateEntry, l as RecallRankingProfile, S as SeededRerankCandidate, m as SeededRerankOptions, V as VectorCandidate, s as seededRerank, n as selectStrongSeeds, o as sharesEntryLineage, p as sharesEpisodeLineage, q as sharesProcedureLineage } from '../../ports-Nj5nd2Ri.js';
 
 /**
  * Runtime slot-policy classes used by claim-centric read surfaces.
@@ -221,6 +117,84 @@ interface RecallClaimKeyTrace {
     /** Current-state trusted same-slot duplicates down-ranked for diversity. */
     redundancyPenalized: number;
 }
+/**
+ * Reciprocal rank fusion facts observed during one recall execution.
+ */
+interface RecallRrfTrace {
+    /** Whether RRF actually fused at least one non-empty channel. */
+    applied: boolean;
+    /** Number of non-empty channels supplied to the fusion helper. */
+    channelCount: number;
+    /** Effective rank constant `k` used for the fusion. */
+    rankConstant: number;
+    /** Number of unique candidates that received a fused RRF score. */
+    fusedCandidateCount: number;
+    /** Maximum normalized RRF score observed across fused candidates. */
+    maxFusedScore: number;
+}
+/**
+ * MMR diversification facts observed during one recall execution.
+ */
+interface RecallMmrTrace {
+    /** Whether MMR actually reordered the shortlist for this execution. */
+    applied: boolean;
+    /** Effective lambda used when MMR ran, or the configured default when skipped. */
+    lambda: number;
+    /**
+     * Candidates that MMR identified as near duplicates and demoted below
+     * their input position. A zero count means no redundancy was observed.
+     */
+    droppedDuplicateCount: number;
+    /** Candidate IDs whose position shifted relative to the input order. */
+    reorderedIds: string[];
+}
+/**
+ * Cross-encoder rerank facts observed during one recall execution.
+ */
+interface RecallCrossEncoderTrace {
+    /** Whether the cross-encoder rerank stage actually ran. */
+    applied: boolean;
+    /** Effective top-K size handed to the cross-encoder. */
+    k: number;
+    /** Blend weight between `crossEncoderScore` and the prior composite score. */
+    alpha: number;
+    /** Wall-clock latency of the cross-encoder rerank stage in milliseconds. */
+    latencyMs: number;
+    /** Stable degraded-mode reason when the rerank was skipped or failed. */
+    degradedReason?: RecallCrossEncoderDegradedReason;
+    /** Candidate IDs whose composite score was reshaped by the rerank. */
+    rescoredIds: string[];
+}
+/**
+ * Stable reasons a cross-encoder rerank may skip or degrade.
+ *
+ * - `not_configured`: no `CrossEncoderPort` was wired on the ports bundle.
+ * - `disabled`: the caller's `rankingPolicy.crossEncoder` is `"disabled"`.
+ * - `no_candidates`: the input shortlist was empty after earlier stages.
+ * - `provider_error`: the port threw or returned malformed data.
+ */
+type RecallCrossEncoderDegradedReason = "not_configured" | "disabled" | "no_candidates" | "provider_error";
+/**
+ * Neighborhood expansion and seeded rerank facts observed during one recall execution.
+ */
+interface RecallNeighborhoodTrace {
+    /** Whether the adapter was asked to expand a lineage neighborhood. */
+    expansionRequested: boolean;
+    /** Whether the adapter exposes the expandNeighborhood port at all. */
+    expansionAvailable: boolean;
+    /** Family kinds requested from the adapter for this execution. */
+    familiesRequested: string[];
+    /** Whether retired rows were allowed into the expansion. */
+    includeRetired: boolean;
+    /** Seed entry IDs chosen before the adapter expansion. */
+    seedIds: string[];
+    /** Unique candidates returned by the adapter expansion. */
+    expansionCandidates: number;
+    /** Strong seed IDs chosen for seededRerank. */
+    strongSeedIds: string[];
+    /** Candidate IDs that received a seededRerank boost. */
+    rerankBoostedIds: string[];
+}
 /**
  * Small typed execution summary emitted by the recall core.
  */
@@ -233,6 +207,14 @@ interface RecallExecutionTraceSummary {
     candidateCounts: RecallCoreCandidateCountsTrace;
     /** Claim-key lineage and diversity shaping facts observed during ranking. */
     claimKey: RecallClaimKeyTrace;
+    /** Reciprocal rank fusion facts observed during ranking. */
+    rrf: RecallRrfTrace;
+    /** Neighborhood expansion and seeded rerank facts observed during ranking. */
+    neighborhood: RecallNeighborhoodTrace;
+    /** MMR diversification facts observed during ranking. */
+    mmr: RecallMmrTrace;
+    /** Cross-encoder rerank facts observed during ranking. */
+    crossEncoder: RecallCrossEncoderTrace;
     /** Whether recall had to degrade into lexical-only ranking. */
     degraded: RecallDegradedTrace;
     /** Core-only timings observed inside the ranking flow. */
@@ -249,6 +231,81 @@ interface RecallTraceSink {
      */
     reportSummary(summary: RecallExecutionTraceSummary): void;
 }
+/**
+ * Tunable ranking policy applied to one recall execution.
+ *
+ * Every field is optional so callers can opt into individual stages
+ * without having to restate the full policy. Evals that A/B one stage
+ * at a time rely on the per-stage kill switches here.
+ */
+interface RecallRankingPolicy {
+    /**
+     * Whether to apply reciprocal rank fusion across retrieval channels.
+     * Defaults to `"enabled"`. When set to `"disabled"`, the recall
+     * pipeline falls back to single-channel vector ordering (with a
+     * lexical fallback when vectors are unavailable) so evals can A/B
+     * the fusion stage without stripping channels from the pipeline.
+     */
+    rrf?: "enabled" | "disabled";
+    /**
+     * Optional override for the RRF rank constant `k`. Higher values
+     * flatten the contribution of the top ranks across channels; lower
+     * values sharpen them. Defaults to the canonical Cormack et al.
+     * constant `60`.
+     */
+    rrfRankConstant?: number;
+    /**
+     * Optional override for the small-pool RRF rank constant `k` that is
+     * used when the fused candidate pool is at or below
+     * `SMALL_POOL_RRF_POOL_SIZE`. Defaults to
+     * `DEFAULT_RRF_SMALL_POOL_RANK_CONSTANT` (`8`), which sharpens the
+     * rank-1 versus rank-2 gap enough to keep small-magnitude recency and
+     * importance differences from flipping a clear vector leader. Set to
+     * the same value as `rrfRankConstant` to disable the sharpening.
+     */
+    rrfSmallPoolRankConstant?: number;
+    /**
+     * Whether to apply the neighborhood expansion plus seeded rerank
+     * stage. Defaults to `"enabled"`. When set to `"disabled"`, the
+     * pipeline skips both the adapter-scoped `expandNeighborhood()` call
+     * and the `seededRerank()` pass so evals can isolate fusion from
+     * lineage-aware rerank effects.
+     */
+    neighborhood?: "enabled" | "disabled";
+    /**
+     * Whether to apply the MMR diversification stage. Defaults to
+     * `"enabled"` so the default pipeline gets diversity out of the box.
+     */
+    mmr?: "enabled" | "disabled";
+    /** Effective MMR lambda in the inclusive 0-1 range. */
+    mmrLambda?: number;
+    /**
+     * Minimum candidate-pool size required for MMR to run. Defaults to
+     * the core `DEFAULT_MMR_MIN_POOL_SIZE`. Set to `0` to disable the
+     * small-pool gate entirely so MMR runs on every non-empty shortlist
+     * (the pre-phase-4 behavior).
+     */
+    mmrMinPoolSize?: number;
+    /**
+     * Whether to apply the cross-encoder rerank stage when a
+     * `CrossEncoderPort` is wired. Defaults to `"enabled"`; evals can pass
+     * `"disabled"` to A/B the stage without unwiring the port.
+     */
+    crossEncoder?: "enabled" | "disabled";
+    /**
+     * Optional top-K override for the cross-encoder shortlist. The stage
+     * reranks only the first K candidates after claim-key shaping and MMR
+     * diversification, so smaller values keep provider cost predictable.
+     */
+    crossEncoderTopK?: number;
+    /**
+     * Blend weight for the cross-encoder score against the prior composite
+     * score. Final relevance becomes
+     * `alpha * crossEncoderScore + (1 - alpha) * compositeScore`.
+     * Clamped into the inclusive 0-1 range; defaults to `0.6`.
+     */
+    crossEncoderAlpha?: number;
+}
 /**
  * Optional execution controls for one recall call.
  */
@@ -257,6 +314,8 @@ interface RecallExecutionOptions {
     trace?: RecallTraceSink;
     /** Optional runtime slot-policy overrides used during claim-aware ranking. */
     slotPolicyConfig?: ClaimSlotPolicyConfig;
+    /** Optional ranking policy overrides, including MMR toggles. */
+    rankingPolicy?: RecallRankingPolicy;
 }
 /**
  * Returns the shared null-object recall trace sink used when no observation is requested.
@@ -265,6 +324,375 @@ interface RecallExecutionOptions {
  */
 declare function createNoopRecallTraceSink(): RecallTraceSink;
 
+/**
+ * Cross-encoder rerank orchestration helper.
+ *
+ * - Keeps core recall free of adapter concerns: the helper only needs a
+ *   `CrossEncoderPort` contract defined in `src/core/ports.ts`.
+ * - Reranks only the top-K shortlist supplied by the caller. Candidates
+ *   past the shortlist keep their input order and composite score.
+ * - Combines the provider score with the prior composite score through a
+ *   linear blend: `alpha * crossEncoderScore + (1 - alpha) * prior`, so
+ *   MMR, claim-key shaping, and seeded rerank still participate in the
+ *   final ordering.
+ * - Fails closed: any thrown or malformed adapter response short-circuits
+ *   into a pass-through result with a trace-visible degraded reason.
+ *
+ * The helper is pure and deterministic given a deterministic port: it
+ * does not mutate callers' inputs, does not read ambient state, and does
+ * not log.
+ */
+/**
+ * Default top-K shortlist size. Bounded small so cross-encoder latency
+ * and provider cost stay predictable even at full recall fan-out.
+ */
+declare const DEFAULT_CROSS_ENCODER_TOP_K = 10;
+/**
+ * Default blend weight between the cross-encoder score and the prior
+ * composite score. Chosen to let the cross-encoder dominate while still
+ * letting prior shaping stages shape the final order.
+ */
+declare const DEFAULT_CROSS_ENCODER_ALPHA = 0.6;
+/**
+ * One input candidate for the cross-encoder rerank helper.
+ *
+ * @template TCandidate - Caller-provided candidate shape passed through untouched.
+ */
+interface CrossEncoderRerankCandidate<TCandidate> {
+    /** Stable identifier used to correlate provider scores back to the candidate. */
+    id: string;
+    /** Caller-provided free-form text fed into the cross-encoder. */
+    text: string;
+    /** Prior composite score retained for the linear blend. */
+    score: number;
+    /** Original candidate reference returned to the caller. */
+    candidate: TCandidate;
+}
+/**
+ * Call options for `applyCrossEncoderRerank`.
+ */
+interface CrossEncoderRerankOptions<TCandidate> {
+    /** Natural-language recall query text. */
+    query: string;
+    /** Candidates in their caller-preferred order. */
+    candidates: readonly CrossEncoderRerankCandidate<TCandidate>[];
+    /** Cross-encoder port when available. When undefined, the stage skips. */
+    port: CrossEncoderPort | undefined;
+    /** Whether the caller explicitly disabled the stage. */
+    disabled?: boolean;
+    /** Optional top-K override. Clamped into `[1, candidates.length]`. */
+    topK?: number;
+    /** Optional blend weight override. Clamped into `[0, 1]`. */
+    alpha?: number;
+}
+/**
+ * Result returned by the cross-encoder rerank helper.
+ *
+ * @template TCandidate - Caller-provided candidate shape passed through untouched.
+ */
+interface CrossEncoderRerankResult<TCandidate> {
+    /** Whether the stage actually invoked the cross-encoder port. */
+    applied: boolean;
+    /** Effective top-K size used by the stage. */
+    k: number;
+    /** Effective blend weight used by the stage. */
+    alpha: number;
+    /** Wall-clock latency of the stage in milliseconds. */
+    latencyMs: number;
+    /** Stable degraded-mode reason when the stage did not rerank. */
+    degradedReason?: RecallCrossEncoderDegradedReason;
+    /**
+     * Candidates in their reranked order. Candidates past the shortlist
+     * keep their input order and their prior score.
+     */
+    candidates: ReadonlyArray<{
+        /** Original candidate reference. */
+        candidate: TCandidate;
+        /** Final composite score after blending. */
+        score: number;
+        /** Raw cross-encoder score when the candidate was reranked. */
+        crossEncoderScore?: number;
+    }>;
+    /** Candidate IDs whose composite score was actually reshaped. */
+    rescoredIds: string[];
+}
+/**
+ * Apply a cross-encoder rerank over the top-K shortlist of candidates.
+ *
+ * The helper is pure: no IO happens outside the provided
+ * `CrossEncoderPort`. The caller owns reading the resulting candidate
+ * order and merging the returned scores back into its ranking model.
+ *
+ * @template TCandidate - Candidate payload shape returned by the caller.
+ * @param options - Orchestration options including the port and limits.
+ * @returns Reranked candidates with trace-visible facts for diagnostics.
+ */
+declare function applyCrossEncoderRerank<TCandidate>(options: CrossEncoderRerankOptions<TCandidate>): Promise<CrossEncoderRerankResult<TCandidate>>;
+
+/**
+ * Reciprocal rank fusion (RRF) helpers used by entry, episode, and procedure
+ * recall to combine multiple retrieval channels into a single relevance signal.
+ *
+ * - A larger default constant (`k = 60`) matching the canonical Cormack et al.
+ *   RRF paper so early ranks do not dominate the fused score.
+ * - A post-pass that normalizes scores into the `0-1` range so downstream
+ *   composite scoring can mix fused relevance with recency and importance.
+ */
+/**
+ * Default RRF rank constant. The Cormack et al. RRF paper uses `k = 60` as a
+ * conservative anchor that flattens the contribution of the top handful of
+ * ranks without letting any single channel dominate.
+ */
+declare const DEFAULT_RRF_RANK_CONSTANT = 60;
+/**
+ * One input channel of ranked identifiers.
+ *
+ * Each channel should be an ordered list from most-relevant to least-relevant,
+ * as produced by vector search, FTS, temporal match, or any other retrieval
+ * path. Channels may overlap or be disjoint and ties inside a channel are
+ * resolved by the caller before passing them in.
+ */
+type RrfChannel = readonly string[];
+/**
+ * Fuse one or more ranked channels into a single normalized score map.
+ *
+ * An identifier's unnormalized RRF score is the sum across channels of
+ * `1 / (rankIndex + k)`, where `rankIndex` is the candidate's zero-based
+ * position inside that channel. Candidates missing from a channel contribute
+ * nothing from that channel.
+ *
+ * The result is then normalized by the theoretical maximum for the supplied
+ * channel count so that an identifier appearing at the top of every supplied
+ * channel maps to `1.0` and a single appearance in one of `N` channels maps
+ * to roughly `1/N` at the very top rank. Empty channels are ignored and do
+ * not count toward the normalization denominator.
+ *
+ * The helper is deliberately pure and side-effect free so the composite
+ * recall pipeline can invoke it for entries, episodes, and procedures
+ * without depending on any adapter.
+ *
+ * @param channels - Ordered rank lists from each retrieval channel.
+ * @param rankConstant - Optional override for the RRF rank constant `k`.
+ * @returns Map from identifier to normalized RRF score in the `0-1` range.
+ */
+declare function rrfFuse(channels: readonly RrfChannel[], rankConstant?: number): Map<string, number>;
+/**
+ * Convenience wrapper for the common two-channel case used by entry and
+ * procedure recall.
+ *
+ * @param vectorRanks - Vector retrieval channel, most-relevant first.
+ * @param lexicalRanks - Lexical retrieval channel, most-relevant first.
+ * @param rankConstant - Optional override for the RRF rank constant `k`.
+ * @returns Map from identifier to normalized RRF score.
+ */
+declare function rrfFuseVectorLexical(vectorRanks: readonly string[], lexicalRanks: readonly string[], rankConstant?: number): Map<string, number>;
+
+/**
+ * Backend-agnostic lexical search tier used to plan adapter queries.
+ */
+type LexicalSearchTier = {
+    tier: "exact";
+    text: string;
+} | {
+    tier: "all_tokens" | "any_tokens";
+    tokens: string[];
+};
+/**
+ * Tokenize free-form text into normalized lexical terms.
+ *
+ * @param text - Source text to tokenize.
+ * @returns Lowercased non-stopword tokens.
+ */
+declare function tokenize(text: string): string[];
+/**
+ * Build a lexical search plan from raw user text.
+ *
+ * @param text - Raw query text.
+ * @returns Exact, all-token, and any-token tiers in cascade order.
+ */
+declare function buildLexicalPlan(text: string): LexicalSearchTier[];
+/**
+ * Compute the lexical overlap score between a query and an entry.
+ *
+ * @param query - Raw recall query text.
+ * @param subject - Entry subject text.
+ * @param content - Entry content text.
+ * @returns Normalized lexical overlap signal in the 0-1 range.
+ */
+declare function computeLexicalScore(query: string, subject: string, content: string): number;
+
+/**
+ * Maximal Marginal Relevance (MMR) diversification helper used by entry,
+ * episode, and procedure recall.
+ *
+ * - Compute pairwise cosine similarity between every candidate embedding.
+ * - For each candidate, combine relevance (cosine similarity to the query)
+ *   with a diversity penalty equal to the maximum pairwise similarity to
+ *   any other candidate.
+ * - Sort candidates by the combined MMR score.
+ *
+ * Unlike the classical iterative MMR, the one-shot variant does not need
+ * the caller to track an already-selected set and produces a stable
+ * re-ranking directly from the candidate list. It is a good fit for the
+ * small shortlists that arrive after RRF, claim-key shaping, and seeded
+ * lineage rerank.
+ */
+/**
+ * Default MMR lambda chosen to favor relevance while still giving the
+ * diversity penalty room to demote near-duplicate candidates. Matches the
+ * value called out in the phase 3 plan.
+ */
+declare const DEFAULT_MMR_LAMBDA = 0.7;
+/**
+ * Threshold above which two candidate embeddings are treated as near
+ * duplicates for trace accounting. Only influences the
+ * `droppedDuplicateCount` counter; it does not affect the MMR ordering.
+ */
+declare const NEAR_DUPLICATE_SIMILARITY = 0.95;
+/**
+ * Input candidate consumed by the MMR helper.
+ */
+interface MmrCandidate {
+    /** Stable identifier used to match candidates back to the caller's list. */
+    id: string;
+    /** Optional embedding vector. Candidates without embeddings skip MMR. */
+    embedding?: number[];
+    /**
+     * Optional caller-provided relevance signal in the 0-1 range. When
+     * supplied, MMR uses this value as the relevance term instead of the
+     * default `cos(queryVector, embedding)` fallback.
+     *
+     * Pipelines that have already performed shaping (historical lineage
+     * boosts, claim-key trust and redundancy penalties) should pass their
+     * shaped composite score so MMR respects that prior work instead of
+     * silently undoing it.
+     */
+    relevance?: number;
+}
+/**
+ * MMR reorder outcome returned to the caller.
+ */
+interface MmrReorderResult {
+    /** Whether MMR actually ran instead of passing through the input order. */
+    applied: boolean;
+    /** Effective lambda that was used during ranking. */
+    lambda: number;
+    /** Reordered candidate IDs. Includes every input candidate exactly once. */
+    orderedIds: string[];
+    /**
+     * Number of candidates that MMR identified as near duplicates (max
+     * pairwise similarity with another candidate at or above
+     * `NEAR_DUPLICATE_SIMILARITY`) and pushed down in the final order.
+     */
+    droppedDuplicateCount: number;
+    /**
+     * IDs whose position changed from the input order as a result of MMR
+     * re-ranking. Empty when MMR was skipped.
+     */
+    reorderedIds: string[];
+}
+/**
+ * MMR call signature.
+ */
+interface MmrOptions {
+    /** Query embedding used as the relevance signal. */
+    queryVector: number[];
+    /** Candidates in their caller-preferred order. */
+    candidates: readonly MmrCandidate[];
+    /** Optional lambda override. Clamped into `[0, 1]`. */
+    lambda?: number;
+    /** Optional final result limit applied after MMR ordering. */
+    limit?: number;
+    /**
+     * Optional minimum pool size required for MMR to run. Defaults to
+     * `DEFAULT_MMR_MIN_POOL_SIZE`. When `candidates.length` is at or below
+     * this size, MMR returns `applied: false` with the input order
+     * preserved. Set to `0` to disable the gate entirely.
+     */
+    minPoolSize?: number;
+}
+/**
+ * Reorder candidates by maximal marginal relevance.
+ *
+ * The helper is pure and does not mutate any input. Candidates without a
+ * usable embedding keep their input order after the embedded candidates,
+ * so missing-embedding fallbacks degrade to pass-through rather than
+ * crashing. When the query vector is empty or at most one candidate has
+ * an embedding, MMR is skipped and the input order is returned as-is.
+ *
+ * @param options - Query embedding plus candidate list and tuning knobs.
+ * @returns Reorder result with ordered IDs, MMR scores, and trace facts.
+ */
+declare function maximalMarginalRelevance(options: MmrOptions): MmrReorderResult;
+
+/**
+ * Score breakdown returned for a ranked recall candidate.
+ */
+interface CandidateScore {
+    score: number;
+    scores: {
+        relevance: number;
+        vector: number;
+        lexical: number;
+        recency: number;
+        importance: number;
+    };
+}
+/**
+ * Compute the tier-aware half-life recency score for an entry.
+ *
+ * @param createdAt - Entry creation timestamp.
+ * @param expiry - Entry durability tier.
+ * @param now - Reference time for the age calculation.
+ * @returns Normalized recency score in the 0-1 range.
+ */
+declare function recencyScore(createdAt: Date | string, expiry: Expiry, now?: Date): number;
+/**
+ * Compute a gaussian recency score centered on an around-date query anchor.
+ *
+ * @param createdAt - Entry creation timestamp.
+ * @param aroundDate - Temporal anchor inferred or provided by the user.
+ * @param radiusDays - Standard deviation-like radius in days.
+ * @returns Normalized temporal proximity score in the 0-1 range.
+ */
+declare function gaussianRecency(createdAt: Date | string, aroundDate: Date, radiusDays: number): number;
+/**
+ * Normalize an importance value from the 1-10 domain into the 0.4-1.0 score range.
+ *
+ * @param importance - Raw entry importance.
+ * @returns Normalized importance score in the 0-1 range.
+ */
+declare function importanceScore(importance: number): number;
+/**
+ * Compute the final recall score and its component breakdown for a candidate.
+ *
+ * Callers are expected to supply the fused `relevance` signal through
+ * reciprocal rank fusion. `vectorSim` and `lexical` are kept on the score
+ * breakdown as evidence-only diagnostics so trace summaries can still
+ * display the raw retrieval signals without influencing the composite.
+ *
+ * @param params - Candidate signal inputs.
+ * @returns Final score plus signal breakdown.
+ */
+declare function scoreCandidate(params: {
+    relevance: number;
+    vectorSim: number;
+    lexical: number;
+    recency: number;
+    importance: number;
+}): CandidateScore;
+/**
+ * Compute cosine similarity between two numeric vectors.
+ *
+ * Non-finite coordinates are treated as zero and negative similarities are clamped
+ * to zero because recall scoring only consumes a 0-1 signal.
+ *
+ * @param left - Left-hand vector.
+ * @param right - Right-hand vector.
+ * @returns Cosine similarity in the 0-1 range.
+ */
+declare function cosineSimilarity(left: number[], right: number[]): number;
+
 /**
  * Execute the v1 recall pipeline against the provided adapter ports.
  *
@@ -292,4 +720,4 @@ declare function inferAroundDate(text: string, now?: Date): Date | null;
  */
 declare function parseRelativeDate(input: string, now?: Date): Date | null;
 
-export { type RecallClaimKeyTrace, type RecallCoreCandidateCountsTrace, type RecallCoreTimingTrace, type RecallDegradedReason, type RecallDegradedTrace, type RecallExecutionOptions, type RecallExecutionTraceSummary, type RecallFilterTrace, RecallInput, type RecallNoResultReason, RecallOutput, type RecallRankingTrace, type RecallTraceSink, buildLexicalPlan, combinedRelevance, computeLexicalScore, cosineSimilarity, createNoopRecallTraceSink, gaussianRecency, importanceScore, inferAroundDate, parseRelativeDate, recall, recencyScore, scoreCandidate, tokenize };
+export { type CrossEncoderRerankCandidate, type CrossEncoderRerankOptions, type CrossEncoderRerankResult, DEFAULT_CROSS_ENCODER_ALPHA, DEFAULT_CROSS_ENCODER_TOP_K, DEFAULT_MMR_LAMBDA, DEFAULT_RRF_RANK_CONSTANT, type MmrCandidate, type MmrOptions, type MmrReorderResult, NEAR_DUPLICATE_SIMILARITY, type RecallClaimKeyTrace, type RecallCoreCandidateCountsTrace, type RecallCoreTimingTrace, type RecallCrossEncoderDegradedReason, type RecallCrossEncoderTrace, type RecallDegradedReason, type RecallDegradedTrace, type RecallExecutionOptions, type RecallExecutionTraceSummary, type RecallFilterTrace, RecallInput, type RecallMmrTrace, type RecallNeighborhoodTrace, type RecallNoResultReason, RecallOutput, type RecallRankingPolicy, type RecallRankingTrace, type RecallRrfTrace, type RecallTraceSink, type RrfChannel, applyCrossEncoderRerank, buildLexicalPlan, computeLexicalScore, cosineSimilarity, createNoopRecallTraceSink, gaussianRecency, importanceScore, inferAroundDate, maximalMarginalRelevance, parseRelativeDate, recall, recencyScore, rrfFuse, rrfFuseVectorLexical, scoreCandidate, tokenize };