@gmickel/gno 1.21.0 → 1.23.0

package/src/pipeline/project-affinity.ts

@@ -0,0 +1,162 @@
+/**
+ * Bounded auxiliary scoring for trusted project affinity.
+ *
+ * @module src/pipeline/project-affinity
+ */
+
+import type {
+  ProjectAffinityMatch,
+  ProjectAffinityResolution,
+} from "../core/project-affinity";
+import type { SearchResult } from "./types";
+
+import {
+  AUXILIARY_RANKING_MAX_CONTRIBUTION,
+  PROJECT_AFFINITY_MAX_CONTRIBUTION,
+} from "../config/types";
+
+export interface ProjectAffinityScoringInput {
+  enabled?: boolean;
+  contribution?: number;
+  resolution: ProjectAffinityResolution;
+}
+
+export interface ProjectAffinityScoreMetadata {
+  affinityAdjustedScore: number;
+  affinityApplied: number;
+  affinityRequested: number;
+  affinityWeight: number;
+  baseScore: number;
+  collectionAlias: string | null;
+  combinedAuxiliaryApplied: number;
+  combinedAuxiliaryCap: number;
+  combinedAuxiliaryRequested: number;
+  finalBlendedScore: number;
+  finalScore: number;
+  matched: boolean;
+  rawScore: number;
+  rawScoreKind: "bm25" | "hybrid_blended" | "normalized" | "vector_distance";
+  rootAlias: string | null;
+  source: ProjectAffinityMatch["source"] | null;
+}
+
+export const SEARCH_RESULT_AFFINITY_METADATA = Symbol(
+  "gno.searchResultAffinityMetadata"
+);
+
+const clamp = (value: number, min: number, max: number): number =>
+  Math.min(max, Math.max(min, value));
+
+export function applyAuxiliaryScore(
+  baseScore: number,
+  contributions: readonly number[]
+): {
+  applied: number;
+  finalScore: number;
+  requested: number;
+} {
+  const requested = [...contributions]
+    .sort((left, right) => left - right)
+    .reduce((total, contribution) => total + contribution, 0);
+  const applied = clamp(
+    requested,
+    -AUXILIARY_RANKING_MAX_CONTRIBUTION,
+    AUXILIARY_RANKING_MAX_CONTRIBUTION
+  );
+  return {
+    requested,
+    applied,
+    finalScore: clamp(baseScore + applied, 0, 1),
+  };
+}
+
+const matchingCollection = (
+  input: ProjectAffinityScoringInput | undefined,
+  collection: string
+): ProjectAffinityMatch | undefined => {
+  if (input?.enabled === false) return undefined;
+  return input?.resolution.matches.find(
+    (match) => match.collection === collection
+  );
+};
+
+export function scoreProjectAffinity(
+  baseScore: number,
+  collection: string,
+  input: ProjectAffinityScoringInput | undefined,
+  raw: {
+    kind: ProjectAffinityScoreMetadata["rawScoreKind"];
+    score: number;
+  } = { kind: "normalized", score: baseScore }
+): ProjectAffinityScoreMetadata {
+  const match = matchingCollection(input, collection);
+  const configuredWeight = clamp(
+    input?.contribution ?? PROJECT_AFFINITY_MAX_CONTRIBUTION,
+    0,
+    PROJECT_AFFINITY_MAX_CONTRIBUTION
+  );
+  const affinityRequested = match ? configuredWeight : 0;
+  const auxiliary = applyAuxiliaryScore(baseScore, [affinityRequested]);
+  const affinityApplied = auxiliary.finalScore - baseScore;
+
+  return {
+    affinityAdjustedScore: auxiliary.finalScore,
+    affinityApplied,
+    affinityRequested,
+    affinityWeight: configuredWeight,
+    baseScore,
+    collectionAlias: match?.collectionAlias ?? null,
+    combinedAuxiliaryApplied: auxiliary.applied,
+    combinedAuxiliaryCap: AUXILIARY_RANKING_MAX_CONTRIBUTION,
+    combinedAuxiliaryRequested: auxiliary.requested,
+    finalBlendedScore: auxiliary.finalScore,
+    finalScore: auxiliary.finalScore,
+    matched: Boolean(match),
+    rawScore: raw.score,
+    rawScoreKind: raw.kind,
+    rootAlias: match?.rootAlias ?? null,
+    source: match?.source ?? null,
+  };
+}
+
+export function hasProjectAffinity(
+  input: ProjectAffinityScoringInput | undefined
+): boolean {
+  return (
+    Boolean(input) &&
+    input?.enabled !== false &&
+    (input?.contribution ?? PROJECT_AFFINITY_MAX_CONTRIBUTION) > 0 &&
+    (input?.resolution.matches.length ?? 0) !== 0
+  );
+}
+
+export function applyProjectAffinity(
+  result: SearchResult,
+  collection: string,
+  input: ProjectAffinityScoringInput | undefined,
+  raw?: {
+    kind: ProjectAffinityScoreMetadata["rawScoreKind"];
+    score: number;
+  }
+): SearchResult {
+  if (!hasProjectAffinity(input)) return result;
+  const metadata = scoreProjectAffinity(result.score, collection, input, raw);
+  result.score = metadata.finalScore;
+  Object.defineProperty(result, SEARCH_RESULT_AFFINITY_METADATA, {
+    configurable: true,
+    enumerable: false,
+    value: metadata,
+    writable: true,
+  });
+  return result;
+}
+
+export function getProjectAffinityMetadata(
+  result: SearchResult
+): ProjectAffinityScoreMetadata | undefined {
+  return (
+    result as SearchResult & {
+      [SEARCH_RESULT_AFFINITY_METADATA]?: ProjectAffinityScoreMetadata;
+    }
+  )[SEARCH_RESULT_AFFINITY_METADATA];
+}

package/src/pipeline/search.ts

@@ -20,6 +20,7 @@ import { err, ok } from "../store/types";
 import { createChunkLookup } from "./chunk-lookup";
 import { matchesExcludedChunks, matchesExcludedText } from "./exclude";
 import { selectBestChunkForSteering } from "./intent";
+import { applyProjectAffinity, hasProjectAffinity } from "./project-affinity";
 import { detectQueryLanguage } from "./query-language";
 import { attachSearchResultContexts } from "./result-context";
 import {
@@ -160,8 +161,9 @@ 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 recencySort = shouldSortByRecency(query);
-  const retrievalLimit = recencySort ? limit * 3 : limit;
+  const retrievalLimit = recencySort || affinityActive ? limit * 3 : limit;
   const temporalRange = resolveTemporalRange(
     query,
     options.since,
@@ -208,6 +210,10 @@ export async function searchBm25(
 
   // Build results
   const results: SearchResult[] = [];
+  const scoringByResult = new WeakMap<
+    SearchResult,
+    { collection: string; rawScore: number }
+  >();
 
   // Pre-fetch all chunks in one batch query (eliminates N+1)
   const uniqueHashes = [
@@ -229,6 +235,11 @@ export async function searchBm25(
     string,
     { fts: FtsResult; chunk: ChunkRow | null; score: number }
   >();
+  const fullAffinityEntries: {
+    fts: FtsResult;
+    chunk: ChunkRow | null;
+    score: number;
+  }[] = [];
 
   for (const fts of ftsResult.value) {
     // Dedup by uri+seq - eliminates rows from mirror_hash join fan-out
@@ -278,6 +289,10 @@ 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) {
+        fullAffinityEntries.push({ fts, chunk, score: fts.score });
+        continue;
+      }
       const docid = fts.docid ?? "";
       const existing = bestByDocid.get(docid);
       if (!existing || fts.score < existing.score) {
@@ -289,16 +304,22 @@ export async function searchBm25(
     const collectionPath = fts.collection
       ? collectionPaths.get(fts.collection)
       : undefined;
-
-    results.push(buildSearchResult({ fts, chunk, collectionPath, options }));
+    const result = buildSearchResult({ fts, chunk, collectionPath, options });
+    if (fts.collection) {
+      scoringByResult.set(result, {
+        collection: fts.collection,
+        rawScore: fts.score,
+      });
+    }
+    results.push(result);
   }
 
   // For --full, fetch full content and build results
   if (options.full) {
     // Sort by raw BM25 score (smaller = better) before building results
-    const sortedEntries = [...bestByDocid.values()].sort(
-      (a, b) => a.score - b.score
-    );
+    const sortedEntries = (
+      affinityActive ? fullAffinityEntries : [...bestByDocid.values()]
+    ).sort((a, b) => a.score - b.score);
     const fullContentResult = await getContentBatch(
       store,
       sortedEntries
@@ -317,18 +338,50 @@ export async function searchBm25(
       const collectionPath = fts.collection
         ? collectionPaths.get(fts.collection)
         : undefined;
-      results.push(
-        buildSearchResult({ fts, chunk, collectionPath, options, fullContent })
-      );
+      const result = buildSearchResult({
+        fts,
+        chunk,
+        collectionPath,
+        options,
+        fullContent,
+      });
+      if (fts.collection) {
+        scoringByResult.set(result, {
+          collection: fts.collection,
+          rawScore: fts.score,
+        });
+      }
+      results.push(result);
     }
   }
 
   // Normalize scores to 0-1 range (batch min-max)
   normalizeBm25Scores(results);
 
+  if (affinityActive) {
+    for (const result of results) {
+      const scoring = scoringByResult.get(result);
+      if (scoring) {
+        applyProjectAffinity(
+          result,
+          scoring.collection,
+          options.projectAffinity,
+          { kind: "bm25", score: scoring.rawScore }
+        );
+      }
+    }
+  }
+
+  const dedupedResults =
+    options.full && affinityActive
+      ? dedupeFullResultsByDocid(results)
+      : results;
+
   // Apply minScore filter after normalization
   const filteredResults =
-    minScore > 0 ? results.filter((r) => r.score >= minScore) : results;
+    minScore > 0
+      ? dedupedResults.filter((r) => r.score >= minScore)
+      : dedupedResults;
 
   if (recencySort) {
     filteredResults.sort((a, b) => {
@@ -345,6 +398,8 @@ export async function searchBm25(
       }
       return b.score - a.score;
     });
+  } else if (affinityActive) {
+    filteredResults.sort((a, b) => b.score - a.score);
   }
 
   const finalResults = filteredResults.slice(0, limit);
@@ -384,3 +439,14 @@ export async function searchBm25(
   }
   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()];
+}

package/src/pipeline/types.ts

@@ -13,6 +13,10 @@ 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 {
+  ProjectAffinityScoreMetadata,
+  ProjectAffinityScoringInput,
+} from "./project-affinity";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Search Result Types
@@ -53,6 +57,8 @@ export interface SearchResultPlannerMetadata {
   retrievalRank: number;
   mirrorHash: string;
   seq: number;
+  /** Original retrieval seq when intent steering selects another snippet. */
+  retrievalSeq?: number;
   sources: FusionSource[];
   graphExpanded: boolean;
   /** Exact canonical chunk coordinates, retained even for full-content output. */
@@ -164,6 +170,8 @@ export interface SearchResults {
 export interface SearchOptions {
   /** Internal receipt seam; never serialized or included in public schemas. */
   traceSession?: RetrievalTraceSession;
+  /** Trusted, already-resolved project affinity; never accepts raw roots. */
+  projectAffinity?: ProjectAffinityScoringInput;
   /** Max results */
   limit?: number;
   /** Min score threshold (0-1) */
@@ -536,4 +544,5 @@ export interface ExplainResult {
   bm25Score?: number;
   vecScore?: number;
   rerankScore?: number;
+  projectAffinity?: ProjectAffinityScoreMetadata;
 }

package/src/pipeline/vsearch.ts

@@ -17,6 +17,7 @@ import { createChunkLookup } from "./chunk-lookup";
 import { formatQueryForEmbedding } from "./contextual";
 import { matchesExcludedChunks, matchesExcludedText } from "./exclude";
 import { selectBestChunkForSteering } from "./intent";
+import { applyProjectAffinity, hasProjectAffinity } from "./project-affinity";
 import { detectQueryLanguage } from "./query-language";
 import { attachSearchResultContexts } from "./result-context";
 import {
@@ -82,8 +83,9 @@ export async function searchVectorWithEmbedding(
   const { store, vectorIndex } = deps;
   const limit = options.limit ?? 20;
   const minScore = options.minScore ?? 0;
+  const affinityActive = hasProjectAffinity(options.projectAffinity);
   const recencySort = shouldSortByRecency(query);
-  const retrievalLimit = recencySort ? limit * 3 : limit;
+  const retrievalLimit = recencySort || affinityActive ? limit * 3 : limit;
   const temporalRange = resolveTemporalRange(
     query,
     options.since,
@@ -104,7 +106,7 @@ export async function searchVectorWithEmbedding(
     queryEmbedding,
     retrievalLimit,
     {
-      minScore,
+      minScore: affinityActive ? undefined : minScore,
       allowedMirrorHashes: options.retrievalScope?.allowedMirrorHashes,
     }
   );
@@ -126,7 +128,7 @@ export async function searchVectorWithEmbedding(
   }
 
   // Cache docs to avoid N+1 queries (filtered by collection and tags)
-  const docByMirrorHash = await buildDocumentMap(store, {
+  const docsByMirrorHash = await buildDocumentMap(store, {
     collection: options.collection,
     relPathPrefix: options.retrievalScope?.relPathPrefix,
     tagsAll: options.tagsAll,
@@ -152,12 +154,18 @@ export async function searchVectorWithEmbedding(
   // For --full, track best score per docid to de-dupe
   const bestByDocid = new Map<
     string,
-    { doc: DocumentInfo; chunk: ChunkInfo; score: number }
+    {
+      doc: DocumentInfo;
+      chunk: ChunkInfo;
+      rankingScore: number;
+      rawDistance: number;
+      score: number;
+    }
   >();
 
   for (const vec of vecResults) {
-    const score = normalizeVectorScore(vec.distance);
-    if (score < minScore) {
+    const baseScore = normalizeVectorScore(vec.distance);
+    if (!affinityActive && baseScore < minScore) {
       continue;
     }
 
@@ -184,56 +192,36 @@ export async function searchVectorWithEmbedding(
     }
 
     // Get document (cached)
-    const doc = docByMirrorHash.get(vec.mirrorHash);
-    if (!doc) {
-      continue;
-    }
-
-    const excluded =
-      matchesExcludedText(
-        [
-          doc.title ?? "",
-          doc.relPath,
-          doc.author ?? "",
-          doc.contentType ?? "",
-          ...(doc.categories ?? []),
-        ],
-        options.exclude
-      ) ||
-      matchesExcludedChunks(
-        chunksMap.get(vec.mirrorHash) ?? [],
-        options.exclude
-      );
-    if (excluded) {
+    const matchingDocs = docsByMirrorHash.get(vec.mirrorHash);
+    if (!matchingDocs || matchingDocs.length === 0) {
       continue;
     }
-
-    // For --full, de-dupe by docid (keep best scoring chunk per doc)
-    if (options.full) {
-      const existing = bestByDocid.get(doc.docid);
-      if (!existing || score > existing.score) {
-        bestByDocid.set(doc.docid, {
-          doc,
-          chunk: {
-            text: chunk.text,
-            language: chunk.language,
-            startLine: chunk.startLine,
-            endLine: chunk.endLine,
-            seq: chunk.seq,
-          },
-          score,
-        });
+    const docs = affinityActive ? matchingDocs : [matchingDocs.at(-1)!];
+    for (const doc of docs) {
+      const collectionPath = collectionPaths.get(doc.collection);
+      const excluded =
+        matchesExcludedText(
+          [
+            doc.title ?? "",
+            doc.relPath,
+            doc.author ?? "",
+            doc.contentType ?? "",
+            ...(doc.categories ?? []),
+          ],
+          options.exclude
+        ) ||
+        matchesExcludedChunks(
+          chunksMap.get(vec.mirrorHash) ?? [],
+          options.exclude
+        );
+      if (excluded) {
+        continue;
       }
-      continue;
-    }
 
-    const collectionPath = collectionPaths.get(doc.collection);
-
-    results.push(
-      attachSearchResultPlannerMetadata(
+      const scoredResult = applyProjectAffinity(
         {
           docid: doc.docid,
-          score,
+          score: baseScore,
           uri: doc.uri,
           title: doc.title ?? undefined,
           contentType: doc.contentType ?? undefined,
@@ -265,7 +253,35 @@ export async function searchVectorWithEmbedding(
               }
             : undefined,
         },
-        {
+        doc.collection,
+        options.projectAffinity,
+        { kind: "vector_distance", score: vec.distance }
+      );
+      if (scoredResult.score < minScore) continue;
+
+      // For --full, de-dupe by docid (keep best scoring chunk per doc)
+      if (options.full) {
+        const existing = bestByDocid.get(doc.docid);
+        if (!existing || scoredResult.score > existing.rankingScore) {
+          bestByDocid.set(doc.docid, {
+            doc,
+            chunk: {
+              text: chunk.text,
+              language: chunk.language,
+              startLine: chunk.startLine,
+              endLine: chunk.endLine,
+              seq: chunk.seq,
+            },
+            rankingScore: scoredResult.score,
+            rawDistance: vec.distance,
+            score: baseScore,
+          });
+        }
+        continue;
+      }
+
+      results.push(
+        attachSearchResultPlannerMetadata(scoredResult, {
           retrievalRank: 0,
           mirrorHash: vec.mirrorHash,
           seq: chunk.seq,
@@ -276,9 +292,9 @@ export async function searchVectorWithEmbedding(
           passageHash: new Bun.CryptoHasher("sha256")
             .update(chunk.text)
             .digest("hex"),
-        }
-      )
-    );
+        })
+      );
+    }
   }
 
   // For --full, fetch full content and build results
@@ -294,47 +310,52 @@ export async function searchVectorWithEmbedding(
     }
     const fullContentByHash = fullContentResult.value;
 
-    for (const { doc, chunk, score } of bestByDocid.values()) {
+    for (const { doc, chunk, rawDistance, score } of bestByDocid.values()) {
       const fullContent = doc.mirrorHash
         ? fullContentByHash.get(doc.mirrorHash)
         : undefined;
 
       const collectionPath = collectionPaths.get(doc.collection);
 
-      const result: SearchResult = {
-        docid: doc.docid,
-        score,
-        uri: doc.uri,
-        title: doc.title ?? undefined,
-        contentType: doc.contentType ?? undefined,
-        categories: doc.categories ?? undefined,
-        line: chunk.startLine,
-        snippet: fullContent ?? chunk.text,
-        snippetLanguage: chunk.language ?? undefined,
-        // --full: no snippetRange (full doc content)
-        snippetRange: fullContent
-          ? undefined
-          : { startLine: chunk.startLine, endLine: chunk.endLine },
-        source: {
-          relPath: doc.relPath,
-          absPath: collectionPath
-            ? `${collectionPath}/${doc.relPath}`
+      const result = applyProjectAffinity(
+        {
+          docid: doc.docid,
+          score,
+          uri: doc.uri,
+          title: doc.title ?? undefined,
+          contentType: doc.contentType ?? undefined,
+          categories: doc.categories ?? undefined,
+          line: chunk.startLine,
+          snippet: fullContent ?? chunk.text,
+          snippetLanguage: chunk.language ?? undefined,
+          // --full: no snippetRange (full doc content)
+          snippetRange: fullContent
+            ? undefined
+            : { startLine: chunk.startLine, endLine: chunk.endLine },
+          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: doc.mirrorHash
+            ? {
+                mirrorHash: doc.mirrorHash,
+                converterId: doc.converterId ?? undefined,
+                converterVersion: doc.converterVersion ?? undefined,
+              }
             : undefined,
-          mime: doc.sourceMime,
-          ext: doc.sourceExt,
-          modifiedAt: doc.sourceMtime,
-          documentDate: doc.frontmatterDate ?? undefined,
-          sizeBytes: doc.sourceSize,
-          sourceHash: doc.sourceHash,
         },
-        conversion: doc.mirrorHash
-          ? {
-              mirrorHash: doc.mirrorHash,
-              converterId: doc.converterId ?? undefined,
-              converterVersion: doc.converterVersion ?? undefined,
-            }
-          : undefined,
-      };
+        doc.collection,
+        options.projectAffinity,
+        { kind: "vector_distance", score: rawDistance }
+      );
       results.push(
         doc.mirrorHash
           ? attachSearchResultPlannerMetadata(result, {
@@ -369,6 +390,8 @@ export async function searchVectorWithEmbedding(
       }
       return b.score - a.score;
     });
+  } else if (affinityActive) {
+    results.sort((a, b) => b.score - a.score);
   }
 
   const finalResults = results.slice(0, limit);
@@ -507,8 +530,8 @@ function matchesCategoryFilter(
 async function buildDocumentMap(
   store: StorePort,
   options: DocumentMapOptions = {}
-): Promise<Map<string, DocumentInfo>> {
-  const result = new Map<string, DocumentInfo>();
+): Promise<Map<string, DocumentInfo[]>> {
+  const result = new Map<string, DocumentInfo[]>();
 
   if (options.mirrorHashes && options.mirrorHashes.length === 0) {
     return result;
@@ -594,7 +617,7 @@ async function buildDocumentMap(
       continue;
     }
 
-    result.set(doc.mirrorHash!, {
+    const documentInfo: DocumentInfo = {
       docid: doc.docid,
       uri: doc.uri,
       title: doc.title,
@@ -612,7 +635,10 @@ async function buildDocumentMap(
       mirrorHash: doc.mirrorHash,
       converterId: doc.converterId,
       converterVersion: doc.converterVersion,
-    });
+    };
+    const matchingDocuments = result.get(doc.mirrorHash!) ?? [];
+    matchingDocuments.push(documentInfo);
+    result.set(doc.mirrorHash!, matchingDocuments);
   }
 
   return result;