@gmickel/gno 1.21.0 → 1.23.0

package/src/mcp/tools/query.ts

@@ -26,6 +26,7 @@ import {
   normalizeContentTypes,
 } from "../../config";
 import { resolveDepthPolicy } from "../../core/depth-policy";
+import { resolveRemoteProjectAffinity } from "../../core/project-affinity-surface";
 import {
   finishRetrievalTraceAfterError,
   retrievalTraceFilters,
@@ -49,6 +50,7 @@ import { normalizeTagFilters, runTool, type ToolResult } from "./index";
 
 interface QueryInput {
   query: string;
+  projectHints?: string[];
   collection?: string;
   limit?: number;
   minScore?: number;
@@ -227,6 +229,10 @@ export function handleQuery(
         hasStructuredModes,
       });
       const { noExpand, noRerank } = depthPolicy;
+      const projectAffinity = await resolveRemoteProjectAffinity(
+        ctx.config,
+        args.projectHints
+      );
       const expandUri =
         !noExpand && !hasStructuredModes
           ? resolveModelUri(ctx.config, "expand", undefined, args.collection)
@@ -253,6 +259,7 @@ export function handleQuery(
         queryModes,
         tagsAll: normalizeTagFilters(args.tagsAll),
         tagsAny: normalizeTagFilters(args.tagsAny),
+        projectAffinity,
       };
 
       try {
@@ -440,6 +447,10 @@ export function handleQueryDiagnose(
           hasStructuredModes,
         });
         const { noExpand, noRerank } = depthPolicy;
+        const projectAffinity = await resolveRemoteProjectAffinity(
+          ctx.config,
+          args.projectHints
+        );
 
         if (!args.fast) {
           const embedResult = await llm.createEmbeddingPort(embedUri, {
@@ -524,6 +535,7 @@ export function handleQueryDiagnose(
           queryModes,
           tagsAll: normalizeTagFilters(args.tagsAll),
           tagsAny: normalizeTagFilters(args.tagsAny),
+          projectAffinity,
           contentTypeRules,
           contentTypeRulesFingerprint:
             fingerprintContentTypeRules(contentTypeRules),

package/src/mcp/tools/search.ts

@@ -11,6 +11,7 @@ import type { SearchResult, SearchResults } from "../../pipeline/types";
 import type { ToolContext } from "../server";
 
 import { decorateUriForIndex, parseUri } from "../../app/constants";
+import { resolveRemoteProjectAffinity } from "../../core/project-affinity-surface";
 import {
   finishRetrievalTraceAfterError,
   retrievalTraceFilters,
@@ -22,6 +23,7 @@ import { normalizeTagFilters, runTool, type ToolResult } from "./index";
 
 interface SearchInput {
   query: string;
+  projectHints?: string[];
   collection?: string;
   limit?: number;
   minScore?: number;
@@ -113,6 +115,10 @@ export function handleSearch(
         }
       }
 
+      const projectAffinity = await resolveRemoteProjectAffinity(
+        ctx.config,
+        args.projectHints
+      );
       const options = {
         limit: args.limit ?? 5,
         minScore: args.minScore,
@@ -126,6 +132,7 @@ export function handleSearch(
         author: args.author,
         tagsAll: normalizeTagFilters(args.tagsAll),
         tagsAny: normalizeTagFilters(args.tagsAny),
+        projectAffinity,
       };
       let traceSession: RetrievalTraceSession | undefined;
       try {

package/src/mcp/tools/vsearch.ts

@@ -12,6 +12,7 @@ import type { ToolContext } from "../server";
 
 import { decorateUriForIndex, parseUri } from "../../app/constants";
 import { createNonTtyProgressRenderer } from "../../cli/progress";
+import { resolveRemoteProjectAffinity } from "../../core/project-affinity-surface";
 import {
   finishRetrievalTraceAfterError,
   retrievalTraceFilters,
@@ -34,6 +35,7 @@ import { normalizeTagFilters, runTool, type ToolResult } from "./index";
 
 interface VsearchInput {
   query: string;
+  projectHints?: string[];
   collection?: string;
   limit?: number;
   minScore?: number;
@@ -135,6 +137,10 @@ export function handleVsearch(
         undefined,
         args.collection
       );
+      const projectAffinity = await resolveRemoteProjectAffinity(
+        ctx.config,
+        args.projectHints
+      );
       const options = {
         limit: args.limit ?? 5,
         minScore: args.minScore,
@@ -147,6 +153,7 @@ export function handleVsearch(
         author: args.author,
         tagsAll: normalizeTagFilters(args.tagsAll),
         tagsAny: normalizeTagFilters(args.tagsAny),
+        projectAffinity,
       };
       let traceSession: RetrievalTraceSession | undefined;
       const traceStart = await startRetrievalTraceRequest({

package/src/pipeline/diagnose.ts

@@ -19,6 +19,12 @@ import { resolveDocRef } from "../core/ref-parser";
 import { err, ok } from "../store/types";
 import { evaluateQueryTargetFilters } from "./filters";
 import { searchHybrid } from "./hybrid";
+import {
+  getProjectAffinityMetadata,
+  type ProjectAffinityScoringInput,
+  type ProjectAffinityScoreMetadata,
+  scoreProjectAffinity,
+} from "./project-affinity";
 
 export type QueryDiagnoseTargetStatus =
   | "not_found"
@@ -46,7 +52,7 @@ export interface QueryDiagnoseStage {
 }
 
 export interface QueryDiagnoseResult {
-  schemaVersion: "1.0";
+  schemaVersion: "1.0" | "1.1";
   query: string;
   target: {
     ref: string;
@@ -65,6 +71,7 @@ export interface QueryDiagnoseResult {
     filterReasons: string[];
   };
   stages: QueryDiagnoseStage[];
+  affinity?: ProjectAffinityScoreMetadata;
   chunk: {
     seq: number | null;
     startLine: number | null;
@@ -155,6 +162,15 @@ function findTargetCandidate(
   );
 }
 
+const hasTrustedProjectAffinityInput = (
+  input: ProjectAffinityScoringInput | undefined
+): boolean =>
+  input?.enabled !== false &&
+  Boolean(
+    input?.resolution.matches.length ||
+    input?.resolution.roots.some((root) => root.source !== "remote_hint")
+  );
+
 export async function diagnoseQueryTarget(
   deps: HybridSearchDeps,
   query: string,
@@ -276,8 +292,28 @@ export async function diagnoseQueryTarget(
     chunks.find((chunk) => chunk.seq === firstMatched?.seq) ??
     chunks[0] ??
     null;
+  const targetResult = searchResult.value.results.find(
+    (result) => result.uri === doc.uri
+  );
+  const lastMatched = trace?.stages
+    .toReversed()
+    .flatMap((stage) => stage.candidates)
+    .find(
+      (candidate) =>
+        candidate.mirrorHash === doc.mirrorHash && targetSeqs.has(candidate.seq)
+    );
+  const affinity =
+    (targetResult ? getProjectAffinityMetadata(targetResult) : undefined) ??
+    (lastMatched && options.projectAffinity
+      ? scoreProjectAffinity(
+          lastMatched.score,
+          doc.collection,
+          options.projectAffinity,
+          { kind: "hybrid_blended", score: lastMatched.score }
+        )
+      : null);
 
-  return ok({
+  const baseResult: QueryDiagnoseResult = {
     ...buildBaseResult(query, options.target, "diagnosed", doc, {
       graphHints,
       chunkCount: chunks.length,
@@ -298,5 +334,14 @@ export async function diagnoseQueryTarget(
       totalResults: searchResult.value.meta.totalResults,
       queryModes: searchResult.value.meta.queryModes,
     },
-  });
+  };
+  return ok(
+    affinity && hasTrustedProjectAffinityInput(options.projectAffinity)
+      ? {
+          ...baseResult,
+          schemaVersion: "1.1",
+          affinity,
+        }
+      : baseResult
+  );
 }

package/src/pipeline/explain.ts

@@ -11,8 +11,11 @@ import type {
   ExplainResult,
   QueryModeSummary,
   RerankedCandidate,
+  SearchResult,
 } from "./types";
 
+import { SEARCH_RESULT_PLANNER_METADATA } from "./types";
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Formatter
 // ─────────────────────────────────────────────────────────────────────────────
@@ -35,7 +38,8 @@ export function formatResultExplain(results: ExplainResult[]): string {
       r.fusionScore !== undefined ||
       r.bm25Score !== undefined ||
       r.vecScore !== undefined ||
-      r.rerankScore !== undefined
+      r.rerankScore !== undefined ||
+      r.projectAffinity !== undefined
     ) {
       msg += " (";
       if (r.fusionScore !== undefined) {
@@ -59,6 +63,12 @@ export function formatResultExplain(results: ExplainResult[]): string {
         }
         msg += `rerank=${r.rerankScore.toFixed(2)}`;
       }
+      if (r.projectAffinity) {
+        if (msg.at(-1) !== "(") {
+          msg += ", ";
+        }
+        msg += `raw=${r.projectAffinity.rawScoreKind}:${r.projectAffinity.rawScore.toFixed(3)}, base=${r.projectAffinity.baseScore.toFixed(3)}, affinity=${r.projectAffinity.affinityApplied.toFixed(3)}/${r.projectAffinity.affinityRequested.toFixed(3)}, auxiliary=${r.projectAffinity.combinedAuxiliaryApplied.toFixed(3)}/${r.projectAffinity.combinedAuxiliaryCap.toFixed(3)}, collection=${r.projectAffinity.collectionAlias}, root=${r.projectAffinity.rootAlias}, source=${r.projectAffinity.source}, final=${r.projectAffinity.finalScore.toFixed(3)}`;
+      }
       msg += ")";
     }
     lines.push(`[explain] result ${r.rank}: ${r.docid} ${msg}`);
@@ -206,18 +216,49 @@ export function explainTimings(timings: StageTimingsInput): ExplainLine {
 
 export function buildExplainResults(
   candidates: RerankedCandidate[],
-  docidMap: Map<string, string>
+  docidMap: Map<string, string>,
+  finalResults?: SearchResult[]
 ): ExplainResult[] {
-  return candidates.slice(0, 20).map((c, i) => {
-    const key = `${c.mirrorHash}:${c.seq}`;
-    return {
-      rank: i + 1,
-      docid: docidMap.get(key) ?? "#unknown",
-      score: c.blendedScore,
-      fusionScore: c.fusionScore,
-      bm25Score: c.bm25Rank !== null ? 1 / (60 + c.bm25Rank) : undefined,
-      vecScore: c.vecRank !== null ? 1 / (60 + c.vecRank) : undefined,
-      rerankScore: c.rerankScore ?? undefined,
-    };
+  if (finalResults) {
+    return finalResults.slice(0, 20).map((result, index) => {
+      const planner = result[SEARCH_RESULT_PLANNER_METADATA];
+      const candidate = candidates.find(
+        (entry) =>
+          entry.mirrorHash === result.conversion?.mirrorHash &&
+          entry.seq === (planner?.retrievalSeq ?? planner?.seq)
+      );
+      return buildExplainResult(result.docid, result.score, index, candidate);
+    });
+  }
+  return candidates.slice(0, 20).map((candidate, index) => {
+    const key = `${candidate.mirrorHash}:${candidate.seq}`;
+    return buildExplainResult(
+      docidMap.get(key) ?? "#unknown",
+      candidate.blendedScore,
+      index,
+      candidate
+    );
   });
 }
+
+function buildExplainResult(
+  docid: string,
+  score: number,
+  index: number,
+  candidate?: RerankedCandidate
+): ExplainResult {
+  if (!candidate) {
+    return { rank: index + 1, docid, score };
+  }
+  return {
+    rank: index + 1,
+    docid,
+    score,
+    fusionScore: candidate.fusionScore,
+    bm25Score:
+      candidate.bm25Rank !== null ? 1 / (60 + candidate.bm25Rank) : undefined,
+    vecScore:
+      candidate.vecRank !== null ? 1 / (60 + candidate.vecRank) : undefined,
+    rerankScore: candidate.rerankScore ?? undefined,
+  };
+}

package/src/pipeline/hybrid.ts

@@ -41,6 +41,11 @@ 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 { detectQueryLanguage } from "./query-language";
 import {
   buildExpansionFromQueryModes,
@@ -301,6 +306,7 @@ 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 limit = options.limit ?? 20;
   const recencySort = shouldSortByRecency(query);
@@ -719,7 +725,7 @@ export async function searchHybrid(
   // ─────────────────────────────────────────────────────────────────────────
   const minScore = options.minScore ?? 0;
   const filteredCandidates =
-    minScore > 0
+    minScore > 0 && !affinityActive
       ? rerankResult.candidates.filter((c) => c.blendedScore >= minScore)
       : rerankResult.candidates;
 
@@ -875,7 +881,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 (results.length >= assemblyLimit) {
+    if (!affinityActive && results.length >= assemblyLimit) {
       break;
     }
 
@@ -939,64 +945,76 @@ export async function searchHybrid(
     }
 
     for (const doc of candidateDocs) {
-      if (results.length >= assemblyLimit) break;
+      if (!affinityActive && results.length >= assemblyLimit) break;
       const filterEval = evaluateDocumentChunkFilters(
         query,
         doc,
         docChunks,
         options
       );
-      if (!filterEval.matches || (options.full && seenDocids.has(doc.docid))) {
+      if (
+        !filterEval.matches ||
+        (options.full && !affinityActive && 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);
-      seenDocids.add(doc.docid);
-      results.push(
-        attachSearchResultPlannerMetadata(
-          {
-            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,
-            },
+      if (options.full && !affinityActive) {
+        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,
           },
-          {
-            retrievalRank: candidateIndex + 1,
+          conversion: {
             mirrorHash: candidate.mirrorHash,
-            seq: snippetChunk.seq,
-            sources: [...candidate.sources].sort(),
-            graphExpanded: candidate.sources.includes("graph"),
-            startLine: snippetChunk.startLine,
-            endLine: snippetChunk.endLine,
-            passageHash: new Bun.CryptoHasher("sha256")
-              .update(snippetChunk.text)
-              .digest("hex"),
-          }
-        )
+            converterId: doc.converterId ?? undefined,
+            converterVersion: doc.converterVersion ?? undefined,
+          },
+        },
+        doc.collection,
+        options.projectAffinity,
+        { kind: "hybrid_blended", score: candidate.blendedScore }
+      );
+      if (scoredResult.score < minScore) continue;
+      results.push(
+        attachSearchResultPlannerMetadata(scoredResult, {
+          retrievalRank: candidateIndex + 1,
+          mirrorHash: candidate.mirrorHash,
+          seq: snippetChunk.seq,
+          ...(affinityActive && snippetChunk.seq !== candidate.seq
+            ? { retrievalSeq: candidate.seq }
+            : {}),
+          sources: [...candidate.sources].sort(),
+          graphExpanded: candidate.sources.includes("graph"),
+          startLine: snippetChunk.startLine,
+          endLine: snippetChunk.endLine,
+          passageHash: new Bun.CryptoHasher("sha256")
+            .update(snippetChunk.text)
+            .digest("hex"),
+        })
       );
     }
   }
@@ -1008,21 +1026,16 @@ export async function searchHybrid(
   // ─────────────────────────────────────────────────────────────────────────
   // 6. Build explain data (if requested)
   // ─────────────────────────────────────────────────────────────────────────
-  const explainData = options.explain
-    ? {
-        lines: explainLines,
-        results: buildExplainResults(
-          filteredCandidates.slice(0, limit),
-          docidMap
-        ),
-      }
-    : undefined;
-
   // ─────────────────────────────────────────────────────────────────────────
   // 7. Return results
   // ─────────────────────────────────────────────────────────────────────────
+  const dedupedResults =
+    options.full && affinityActive
+      ? dedupeFullResultsByDocid(results)
+      : results;
+
   if (recencySort) {
-    results.sort((a, b) => {
+    dedupedResults.sort((a, b) => {
       const aTs = resolveRecencyTimestamp(
         a.source.documentDate,
         a.source.modifiedAt
@@ -1036,9 +1049,26 @@ export async function searchHybrid(
       }
       return b.score - a.score;
     });
+  } else if (affinityActive) {
+    dedupedResults.sort((a, b) => b.score - a.score);
   }
 
-  const finalResults = results.slice(0, limit);
+  const finalResults = dedupedResults.slice(0, limit);
+  const explainData = options.explain
+    ? {
+        lines: explainLines,
+        results: affinityActive
+          ? buildExplainResults(filteredCandidates, docidMap, finalResults).map(
+              (result, index) => ({
+                ...result,
+                projectAffinity: getProjectAffinityMetadata(
+                  finalResults[index]!
+                ),
+              })
+            )
+          : buildExplainResults(filteredCandidates.slice(0, limit), docidMap),
+      }
+    : undefined;
   await attachSearchResultContexts(store, finalResults);
 
   const output: SearchResults = {
@@ -1143,3 +1173,14 @@ export async function searchHybrid(
   }
   return ok(output);
 }
+
+function dedupeFullResultsByDocid(results: SearchResult[]): SearchResult[] {
+  const bestByDocid = new Map<string, SearchResult>();
+  for (const result of results) {
+    const existing = bestByDocid.get(result.docid);
+    if (!existing || result.score > existing.score) {
+      bestByDocid.set(result.docid, result);
+    }
+  }
+  return [...bestByDocid.values()];
+}