@gmickel/gno 1.26.0 → 1.27.1

package/src/pipeline/hybrid.ts

@@ -7,7 +7,7 @@
 
 import type { Config } from "../config/types";
 import type { EmbeddingPort, GenerationPort, RerankPort } from "../llm/types";
-import type { StorePort } from "../store/types";
+import type { DocumentRow, StorePort } from "../store/types";
 import type { VectorIndexPort } from "../store/vector/types";
 import type {
   ExpansionResult,
@@ -20,9 +20,16 @@ import type {
   SearchResults,
 } from "./types";
 
+import { normalizeContentTypes } from "../config/content-types";
 import { embedTextsWithRecovery } from "../embed/batch";
 import { err, ok } from "../store/types";
 import { createChunkLookup } from "./chunk-lookup";
+import {
+  attachAuxiliaryScoreMetadata,
+  hasAuxiliaryRanking,
+  scoreContentTypeBoost,
+  sortByFinalScoreStable,
+} from "./content-type-boost";
 import { formatQueryForEmbedding } from "./contextual";
 import { expandQuery } from "./expansion";
 import {
@@ -41,11 +48,7 @@ import { evaluateDocumentChunkFilters } from "./filters";
 import { type RankedInput, rrfFuse, toRankedInput } from "./fusion";
 import { expandGraphCandidates } from "./graph-retrieval";
 import { selectBestChunkForSteering } from "./intent";
-import {
-  applyProjectAffinity,
-  getProjectAffinityMetadata,
-  hasProjectAffinity,
-} from "./project-affinity";
+import { hasProjectAffinity } from "./project-affinity";
 import { detectQueryLanguage } from "./query-language";
 import {
   buildExpansionFromQueryModes,
@@ -63,7 +66,10 @@ import {
   attachSearchResultPlannerMetadata,
   attachSearchResultsTraceMetadata,
 } from "./trace-metadata";
-import { DEFAULT_PIPELINE_CONFIG } from "./types";
+import {
+  DEFAULT_PIPELINE_CONFIG,
+  SEARCH_RESULT_PLANNER_METADATA,
+} from "./types";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Dependencies
@@ -306,7 +312,13 @@ export async function searchHybrid(
   const runStartedAt = performance.now();
   const { store, vectorIndex, embedPort, expandPort, rerankPort } = deps;
   const pipelineConfig = deps.pipelineConfig ?? DEFAULT_PIPELINE_CONFIG;
-  const affinityActive = hasProjectAffinity(options.projectAffinity);
+  const contentTypeRules =
+    options.contentTypeRules ??
+    normalizeContentTypes(deps.config.contentTypes ?? []).rules;
+  const auxiliaryRankingActive = hasAuxiliaryRanking(
+    options.projectAffinity,
+    contentTypeRules
+  );
 
   const limit = options.limit ?? 20;
   const recencySort = shouldSortByRecency(query);
@@ -685,6 +697,68 @@ export async function searchHybrid(
     explainFusion(pipelineConfig.rrf.k, fusedCandidates.length)
   );
 
+  // Auxiliary scores enter after fusion normalization and before rerank
+  // blending. The reranker therefore remains the final ordering authority,
+  // including its lexical top-hit guardrail.
+  let prefetchedDocuments: DocumentRow[] | undefined;
+  const auxiliaryBaseScores = new Map<string, number>();
+  const preRerankAdjustedCandidates = new Set<string>();
+  let adjustNormalizedFusionScore:
+    | ((
+        candidate: (typeof fusedCandidates)[number],
+        normalizedScore: number
+      ) => number)
+    | undefined;
+  if (auxiliaryRankingActive) {
+    const prefetchedDocumentsResult = await store.getDocumentsByMirrorHashes(
+      [...new Set(fusedCandidates.map((candidate) => candidate.mirrorHash))],
+      {
+        collection: options.collection,
+        activeOnly: true,
+      }
+    );
+    if (!prefetchedDocumentsResult.ok) {
+      return err("QUERY_FAILED", prefetchedDocumentsResult.error.message);
+    }
+    prefetchedDocuments = prefetchedDocumentsResult.value;
+    const scoringDocumentsByHash = new Map<string, DocumentRow[]>();
+    for (const document of [...prefetchedDocuments].sort((left, right) => {
+      if (left.uri !== right.uri) return left.uri.localeCompare(right.uri);
+      return left.docid.localeCompare(right.docid);
+    })) {
+      if (!document.mirrorHash) continue;
+      const documents = scoringDocumentsByHash.get(document.mirrorHash) ?? [];
+      documents.push(document);
+      scoringDocumentsByHash.set(document.mirrorHash, documents);
+    }
+    adjustNormalizedFusionScore = (candidate, normalizedScore) => {
+      const candidateKey = `${candidate.mirrorHash}:${candidate.seq}`;
+      auxiliaryBaseScores.set(candidateKey, normalizedScore);
+      const documents = scoringDocumentsByHash.get(candidate.mirrorHash);
+      if (!documents?.length) return normalizedScore;
+      const projectedScores = documents.map(
+        (document) =>
+          scoreContentTypeBoost(
+            normalizedScore,
+            document.contentType ?? undefined,
+            document.contentTypeSource,
+            document.relPath,
+            document.collection,
+            contentTypeRules,
+            options.projectAffinity,
+            { kind: "hybrid_blended", score: normalizedScore }
+          ).projectAffinity.finalScore
+      );
+      const agreedScore = projectedScores[0] ?? normalizedScore;
+      const projectionsAgree = projectedScores.every(
+        (score) => Math.abs(score - agreedScore) < 1e-9
+      );
+      if (!projectionsAgree) return normalizedScore;
+      preRerankAdjustedCandidates.add(candidateKey);
+      return agreedScore;
+    };
+  }
+
   // ─────────────────────────────────────────────────────────────────────────
   // 4. Reranking
   // ─────────────────────────────────────────────────────────────────────────
@@ -697,6 +771,7 @@ export async function searchHybrid(
       maxCandidates: candidateLimit,
       blendingSchedule: pipelineConfig.blendingSchedule,
       intent: options.intent,
+      adjustNormalizedFusionScore,
     }
   );
   if (rerankResult.fallbackReason === "disabled") {
@@ -725,7 +800,7 @@ export async function searchHybrid(
   // ─────────────────────────────────────────────────────────────────────────
   const minScore = options.minScore ?? 0;
   const filteredCandidates =
-    minScore > 0 && !affinityActive
+    minScore > 0 && !auxiliaryRankingActive
       ? rerankResult.candidates.filter((c) => c.blendedScore >= minScore)
       : rerankResult.candidates;
 
@@ -739,30 +814,31 @@ export async function searchHybrid(
   const neededHashes = new Set(filteredCandidates.map((c) => c.mirrorHash));
 
   // Fetch only needed documents and collections.
-  const docsResult = await store.getDocumentsByMirrorHashes([...neededHashes], {
-    collection: options.collection,
-    activeOnly: true,
-  });
-  const collectionsResult = await store.getCollections();
-
-  if (!docsResult.ok) {
-    return err("QUERY_FAILED", docsResult.error.message);
+  let documents = prefetchedDocuments;
+  if (!documents) {
+    const docsResult = await store.getDocumentsByMirrorHashes(
+      [...neededHashes],
+      {
+        collection: options.collection,
+        activeOnly: true,
+      }
+    );
+    if (!docsResult.ok) {
+      return err("QUERY_FAILED", docsResult.error.message);
+    }
+    documents = docsResult.value;
   }
+  const collectionsResult = await store.getCollections();
 
   // Build lookup maps.
-  const docsByMirrorHash = new Map<
-    string,
-    (typeof docsResult.value)[number][]
-  >();
-  const addDocument = (doc: (typeof docsResult.value)[number]): void => {
+  const docsByMirrorHash = new Map<string, DocumentRow[]>();
+  const addDocument = (doc: DocumentRow): void => {
     if (!doc.mirrorHash) return;
     const docs = docsByMirrorHash.get(doc.mirrorHash) ?? [];
     docs.push(doc);
     docsByMirrorHash.set(doc.mirrorHash, docs);
   };
-  const matchesMetadataFilters = (
-    doc: (typeof docsResult.value)[number]
-  ): boolean => {
+  const matchesMetadataFilters = (doc: DocumentRow): boolean => {
     const relPathPrefix = options.retrievalScope?.relPathPrefix;
     if (
       relPathPrefix !== undefined &&
@@ -798,9 +874,9 @@ export async function searchHybrid(
   // Collect doc IDs that need tag filtering
   const needsTagFilter = options.tagsAll?.length || options.tagsAny?.length;
   const docIdsForTagCheck: number[] = [];
-  const candidateDocs: (typeof docsResult.value)[number][] = [];
+  const candidateDocs: DocumentRow[] = [];
 
-  for (const doc of docsResult.value) {
+  for (const doc of documents) {
     if (!doc.mirrorHash) {
       continue;
     }
@@ -881,7 +957,7 @@ export async function searchHybrid(
   // Iterate until we have enough results (don't slice early - deduping may skip candidates)
   for (const [candidateIndex, candidate] of filteredCandidates.entries()) {
     // Stop when we have enough results
-    if (!affinityActive && results.length >= assemblyLimit) {
+    if (!auxiliaryRankingActive && results.length >= assemblyLimit) {
       break;
     }
 
@@ -945,7 +1021,7 @@ export async function searchHybrid(
     }
 
     for (const doc of candidateDocs) {
-      if (!affinityActive && results.length >= assemblyLimit) break;
+      if (!auxiliaryRankingActive && results.length >= assemblyLimit) break;
       const filterEval = evaluateDocumentChunkFilters(
         query,
         doc,
@@ -954,49 +1030,72 @@ export async function searchHybrid(
       );
       if (
         !filterEval.matches ||
-        (options.full && !affinityActive && seenDocids.has(doc.docid))
+        (options.full && !auxiliaryRankingActive && seenDocids.has(doc.docid))
       ) {
         continue;
       }
       const docidKey = `${candidate.mirrorHash}:${candidate.seq}`;
       if (!docidMap.has(docidKey)) docidMap.set(docidKey, doc.docid);
       const collectionPath = collectionPaths.get(doc.collection);
-      if (options.full && !affinityActive) {
+      if (options.full && !auxiliaryRankingActive) {
         seenDocids.add(doc.docid);
       }
-      const scoredResult = applyProjectAffinity(
-        {
-          docid: doc.docid,
-          score: candidate.blendedScore,
-          uri: doc.uri,
-          title: doc.title ?? undefined,
-          contentType: doc.contentType ?? undefined,
-          categories: doc.categories ?? undefined,
-          line: snippetChunk.startLine,
-          snippet,
-          snippetLanguage: chunk.language ?? undefined,
-          snippetRange,
-          source: {
-            relPath: doc.relPath,
-            absPath: collectionPath
-              ? `${collectionPath}/${doc.relPath}`
-              : undefined,
-            mime: doc.sourceMime,
-            ext: doc.sourceExt,
-            modifiedAt: doc.sourceMtime,
-            documentDate: doc.frontmatterDate ?? undefined,
-            sizeBytes: doc.sourceSize,
-            sourceHash: doc.sourceHash,
-          },
-          conversion: {
-            mirrorHash: candidate.mirrorHash,
-            converterId: doc.converterId ?? undefined,
-            converterVersion: doc.converterVersion ?? undefined,
-          },
+      const baseResult: SearchResult = {
+        docid: doc.docid,
+        score: candidate.blendedScore,
+        uri: doc.uri,
+        title: doc.title ?? undefined,
+        contentType: doc.contentType ?? undefined,
+        categories: doc.categories ?? undefined,
+        line: snippetChunk.startLine,
+        snippet,
+        snippetLanguage: chunk.language ?? undefined,
+        snippetRange,
+        source: {
+          relPath: doc.relPath,
+          absPath: collectionPath
+            ? `${collectionPath}/${doc.relPath}`
+            : undefined,
+          mime: doc.sourceMime,
+          ext: doc.sourceExt,
+          modifiedAt: doc.sourceMtime,
+          documentDate: doc.frontmatterDate ?? undefined,
+          sizeBytes: doc.sourceSize,
+          sourceHash: doc.sourceHash,
         },
+        conversion: {
+          mirrorHash: candidate.mirrorHash,
+          converterId: doc.converterId ?? undefined,
+          converterVersion: doc.converterVersion ?? undefined,
+        },
+      };
+      const auxiliaryBaseScore =
+        auxiliaryBaseScores.get(`${candidate.mirrorHash}:${candidate.seq}`) ??
+        candidate.blendedScore;
+      const candidateKey = `${candidate.mirrorHash}:${candidate.seq}`;
+      const composedBeforeRerank =
+        preRerankAdjustedCandidates.has(candidateKey);
+      const scoringBaseScore =
+        rerankResult.reranked && !composedBeforeRerank
+          ? candidate.blendedScore
+          : auxiliaryBaseScore;
+      const scored = scoreContentTypeBoost(
+        scoringBaseScore,
+        doc.contentType ?? undefined,
+        doc.contentTypeSource,
+        doc.relPath,
         doc.collection,
+        contentTypeRules,
         options.projectAffinity,
-        { kind: "hybrid_blended", score: candidate.blendedScore }
+        { kind: "hybrid_blended", score: scoringBaseScore }
+      );
+      const scoredResult = attachAuxiliaryScoreMetadata(
+        baseResult,
+        scored,
+        rerankResult.reranked && composedBeforeRerank
+          ? candidate.blendedScore
+          : scored.projectAffinity.finalScore,
+        hasProjectAffinity(options.projectAffinity)
       );
       if (scoredResult.score < minScore) continue;
       results.push(
@@ -1004,7 +1103,7 @@ export async function searchHybrid(
           retrievalRank: candidateIndex + 1,
           mirrorHash: candidate.mirrorHash,
           seq: snippetChunk.seq,
-          ...(affinityActive && snippetChunk.seq !== candidate.seq
+          ...(auxiliaryRankingActive && snippetChunk.seq !== candidate.seq
             ? { retrievalSeq: candidate.seq }
             : {}),
           sources: [...candidate.sources].sort(),
@@ -1030,7 +1129,7 @@ export async function searchHybrid(
   // 7. Return results
   // ─────────────────────────────────────────────────────────────────────────
   const dedupedResults =
-    options.full && affinityActive
+    options.full && auxiliaryRankingActive
       ? dedupeFullResultsByDocid(results)
       : results;
 
@@ -1049,23 +1148,20 @@ export async function searchHybrid(
       }
       return b.score - a.score;
     });
-  } else if (affinityActive) {
-    dedupedResults.sort((a, b) => b.score - a.score);
+  } else if (auxiliaryRankingActive && !rerankResult.reranked) {
+    sortByFinalScoreStable(dedupedResults);
   }
 
   const finalResults = dedupedResults.slice(0, limit);
+  for (const [index, result] of finalResults.entries()) {
+    const metadata = result[SEARCH_RESULT_PLANNER_METADATA];
+    if (metadata) metadata.retrievalRank = index + 1;
+  }
   const explainData = options.explain
     ? {
         lines: explainLines,
-        results: affinityActive
-          ? buildExplainResults(filteredCandidates, docidMap, finalResults).map(
-              (result, index) => ({
-                ...result,
-                projectAffinity: getProjectAffinityMetadata(
-                  finalResults[index]!
-                ),
-              })
-            )
+        results: auxiliaryRankingActive
+          ? buildExplainResults(filteredCandidates, docidMap, finalResults)
           : buildExplainResults(filteredCandidates.slice(0, limit), docidMap),
       }
     : undefined;

package/src/pipeline/rerank.ts

@@ -26,6 +26,11 @@ export interface RerankOptions {
   blendingSchedule?: BlendingTier[];
   /** Optional disambiguating context for reranking */
   intent?: string;
+  /** Apply bounded auxiliary scoring after fusion normalization, before blend. */
+  adjustNormalizedFusionScore?: (
+    candidate: FusionCandidate,
+    normalizedScore: number
+  ) => number;
 }
 
 export interface RerankResult {
@@ -184,15 +189,41 @@ export async function rerankCandidates(
     const v = (score - minFusionAll) / fusionRangeAll;
     return Math.max(0, Math.min(1, v));
   };
+  const adjustedFusionScore = (candidate: FusionCandidate): number => {
+    const normalized = normalizeFusionScore(candidate.fusionScore);
+    const adjusted = options.adjustNormalizedFusionScore?.(
+      candidate,
+      normalized
+    );
+    return adjusted === undefined
+      ? normalized
+      : Math.max(0, Math.min(1, adjusted));
+  };
+  const sortAdjustedCandidates = (
+    adjustedCandidates: RerankedCandidate[]
+  ): RerankedCandidate[] => {
+    if (!options.adjustNormalizedFusionScore) {
+      return adjustedCandidates;
+    }
+    return adjustedCandidates.sort(
+      (left, right) =>
+        right.blendedScore - left.blendedScore ||
+        `${left.mirrorHash}:${left.seq}`.localeCompare(
+          `${right.mirrorHash}:${right.seq}`
+        )
+    );
+  };
 
   // No reranker: return candidates with normalized fusion scores
   if (!rerankPort) {
     return {
-      candidates: candidates.map((c) => ({
-        ...c,
-        rerankScore: null,
-        blendedScore: normalizeFusionScore(c.fusionScore),
-      })),
+      candidates: sortAdjustedCandidates(
+        candidates.map((c) => ({
+          ...c,
+          rerankScore: null,
+          blendedScore: adjustedFusionScore(c),
+        }))
+      ),
       reranked: false,
       fallbackReason: "disabled",
     };
@@ -239,11 +270,13 @@ export async function rerankCandidates(
 
   if (!rerankResult.ok) {
     return {
-      candidates: candidates.map((c) => ({
-        ...c,
-        rerankScore: null,
-        blendedScore: normalizeFusionScore(c.fusionScore),
-      })),
+      candidates: sortAdjustedCandidates(
+        candidates.map((c) => ({
+          ...c,
+          rerankScore: null,
+          blendedScore: adjustedFusionScore(c),
+        }))
+      ),
       reranked: false,
       fallbackReason: "error",
     };
@@ -277,7 +310,7 @@ export async function rerankCandidates(
       rerankScore !== null ? normalizeRerankScore(rerankScore) : null;
 
     const position = i + 1;
-    const normalizedFusion = normalizeFusionScore(c.fusionScore);
+    const normalizedFusion = adjustedFusionScore(c);
     const blendedScore =
       normalizedRerankScore !== null
         ? blend(normalizedFusion, normalizedRerankScore, position, schedule)
@@ -292,10 +325,7 @@ export async function rerankCandidates(
     ...remaining.map((c) => ({
       ...c,
       rerankScore: null,
-      blendedScore: Math.max(
-        0,
-        Math.min(1, normalizeFusionScore(c.fusionScore) * 0.5)
-      ),
+      blendedScore: Math.max(0, Math.min(1, adjustedFusionScore(c) * 0.5)),
     })),
   ];
 

package/src/pipeline/search.ts

@@ -18,9 +18,14 @@ import type {
 import { getContentBatch } from "../store/content-batch";
 import { err, ok } from "../store/types";
 import { createChunkLookup } from "./chunk-lookup";
+import {
+  applyContentTypeBoost,
+  hasAuxiliaryRanking,
+  sortByFinalScoreStable,
+} from "./content-type-boost";
 import { matchesExcludedChunks, matchesExcludedText } from "./exclude";
 import { selectBestChunkForSteering } from "./intent";
-import { applyProjectAffinity, hasProjectAffinity } from "./project-affinity";
+import { hasProjectAffinity } from "./project-affinity";
 import { detectQueryLanguage } from "./query-language";
 import { attachSearchResultContexts } from "./result-context";
 import {
@@ -161,9 +166,14 @@ export async function searchBm25(
   const traceStartedAt = options.traceSession ? performance.now() : 0;
   const limit = options.limit ?? 20;
   const minScore = options.minScore ?? 0;
-  const affinityActive = hasProjectAffinity(options.projectAffinity);
+  const auxiliaryRankingActive = hasAuxiliaryRanking(
+    options.projectAffinity,
+    options.contentTypeRules
+  );
+  const projectAffinityActive = hasProjectAffinity(options.projectAffinity);
   const recencySort = shouldSortByRecency(query);
-  const retrievalLimit = recencySort || affinityActive ? limit * 3 : limit;
+  const retrievalLimit =
+    recencySort || projectAffinityActive ? limit * 3 : limit;
   const temporalRange = resolveTemporalRange(
     query,
     options.since,
@@ -212,7 +222,11 @@ export async function searchBm25(
   const results: SearchResult[] = [];
   const scoringByResult = new WeakMap<
     SearchResult,
-    { collection: string; rawScore: number }
+    {
+      collection: string;
+      contentTypeSource?: string;
+      rawScore: number;
+    }
   >();
 
   // Pre-fetch all chunks in one batch query (eliminates N+1)
@@ -289,7 +303,7 @@ export async function searchBm25(
     // For --full, de-dupe by docid (keep best scoring chunk per doc)
     // Raw BM25: smaller (more negative) is better
     if (options.full) {
-      if (affinityActive) {
+      if (auxiliaryRankingActive) {
         fullAffinityEntries.push({ fts, chunk, score: fts.score });
         continue;
       }
@@ -308,6 +322,7 @@ export async function searchBm25(
     if (fts.collection) {
       scoringByResult.set(result, {
         collection: fts.collection,
+        contentTypeSource: fts.contentTypeSource,
         rawScore: fts.score,
       });
     }
@@ -318,7 +333,7 @@ export async function searchBm25(
   if (options.full) {
     // Sort by raw BM25 score (smaller = better) before building results
     const sortedEntries = (
-      affinityActive ? fullAffinityEntries : [...bestByDocid.values()]
+      auxiliaryRankingActive ? fullAffinityEntries : [...bestByDocid.values()]
     ).sort((a, b) => a.score - b.score);
     const fullContentResult = await getContentBatch(
       store,
@@ -348,6 +363,7 @@ export async function searchBm25(
       if (fts.collection) {
         scoringByResult.set(result, {
           collection: fts.collection,
+          contentTypeSource: fts.contentTypeSource,
           rawScore: fts.score,
         });
       }
@@ -358,14 +374,16 @@ export async function searchBm25(
   // Normalize scores to 0-1 range (batch min-max)
   normalizeBm25Scores(results);
 
-  if (affinityActive) {
+  if (auxiliaryRankingActive) {
     for (const result of results) {
       const scoring = scoringByResult.get(result);
       if (scoring) {
-        applyProjectAffinity(
+        applyContentTypeBoost(
           result,
           scoring.collection,
+          options.contentTypeRules,
           options.projectAffinity,
+          scoring.contentTypeSource,
           { kind: "bm25", score: scoring.rawScore }
         );
       }
@@ -373,7 +391,7 @@ export async function searchBm25(
   }
 
   const dedupedResults =
-    options.full && affinityActive
+    options.full && auxiliaryRankingActive
       ? dedupeFullResultsByDocid(results)
       : results;
 
@@ -398,8 +416,8 @@ export async function searchBm25(
       }
       return b.score - a.score;
     });
-  } else if (affinityActive) {
-    filteredResults.sort((a, b) => b.score - a.score);
+  } else if (auxiliaryRankingActive) {
+    sortByFinalScoreStable(filteredResults);
   }
 
   const finalResults = filteredResults.slice(0, limit);

package/src/pipeline/types.ts

@@ -5,6 +5,7 @@
  * @module src/pipeline/types
  */
 
+import type { NormalizedContentTypeRule } from "../config/content-types";
 import type {
   ContextCapsuleV1,
   ContextCapsuleVerification,
@@ -13,6 +14,7 @@ import type { RetrievalTraceSession } from "../core/retrieval-trace-session";
 import type { StoreResult } from "../store/types";
 import type { ClaimVerificationResult } from "./claim-verification";
 import type { SemanticVerificationCapability } from "./claim-verifier";
+import type { ContentTypeBoostScoreMetadata } from "./content-type-boost";
 import type {
   ProjectAffinityScoreMetadata,
   ProjectAffinityScoringInput,
@@ -132,10 +134,7 @@ export interface SearchMeta {
   /** Explicit exclusion terms applied */
   exclude?: string[];
   /** Explain data (when --explain is used) */
-  explain?: {
-    lines: ExplainLine[];
-    results: ExplainResult[];
-  };
+  explain?: SearchExplain;
   /** Internal diagnose trace, only populated when diagnoseTrace is enabled */
   trace?: QueryDiagnoseTrace;
 }
@@ -172,6 +171,8 @@ export interface SearchOptions {
   traceSession?: RetrievalTraceSession;
   /** Trusted, already-resolved project affinity; never accepts raw roots. */
   projectAffinity?: ProjectAffinityScoringInput;
+  /** Internal normalized rules used by bounded content-type scoring. */
+  contentTypeRules?: NormalizedContentTypeRule[];
   /** Max results */
   limit?: number;
   /** Min score threshold (0-1) */
@@ -459,6 +460,8 @@ export interface AskMeta {
   answerGenerated?: boolean;
   totalResults?: number;
   answerContext?: AnswerContextExplain;
+  /** Optional retrieval scoring explanation; absent from normal output. */
+  explain?: SearchExplain;
   verificationRequested?: boolean;
   abstained?: boolean;
 }
@@ -545,4 +548,10 @@ export interface ExplainResult {
   vecScore?: number;
   rerankScore?: number;
   projectAffinity?: ProjectAffinityScoreMetadata;
+  contentTypeBoost?: ContentTypeBoostScoreMetadata;
+}
+
+export interface SearchExplain {
+  lines: ExplainLine[];
+  results: ExplainResult[];
 }