@gmickel/gno 1.22.0 → 1.23.0

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;

package/src/sdk/client.ts

@@ -38,6 +38,7 @@ import type {
   GnoQueryOptions,
   GnoRefactorNoteResult,
   GnoRenameNoteOptions,
+  GnoSearchOptions,
   GnoUpdateOptions,
   GnoVectorSearchOptions,
   KnowledgeChangesResult,
@@ -97,6 +98,10 @@ import {
 } from "../core/knowledge-delta";
 import { resolveNoteCreatePlan } from "../core/note-creation";
 import { resolveNotePreset } from "../core/note-presets";
+import {
+  ProjectAffinityInputError,
+  resolveRemoteProjectAffinity,
+} from "../core/project-affinity-surface";
 import { RetrievalTraceManagementService } from "../core/retrieval-trace-management";
 import {
   finishRetrievalTraceAfterError,
@@ -160,6 +165,20 @@ interface RuntimePorts {
   vectorIndex: VectorIndexPort | null;
 }
 
+const resolveSdkProjectAffinity = async (
+  config: Config,
+  projectHints: readonly string[] | undefined
+) => {
+  try {
+    return await resolveRemoteProjectAffinity(config, projectHints);
+  } catch (error) {
+    if (error instanceof ProjectAffinityInputError) {
+      throw sdkError("VALIDATION", error.message);
+    }
+    throw error;
+  }
+};
+
 function unwrapStore<T>(
   result: StoreResult<T>,
   code: "STORE" | "RUNTIME" = "STORE"
@@ -471,17 +490,22 @@ class GnoClientImpl implements GnoClient {
 
   async search(
     query: string,
-    options: import("../pipeline/types").SearchOptions = {}
+    options: GnoSearchOptions = {}
   ): Promise<SearchResults> {
     this.assertOpen();
     let traceSession: RetrievalTraceSession | null = null;
     try {
+      const { projectHints, ...searchOptions } = options;
+      const projectAffinity = await resolveSdkProjectAffinity(
+        this.config,
+        projectHints
+      );
       traceSession = unwrapStore(
         await startRetrievalTraceRequest({
           store: this.store,
           config: this.config,
           query,
-          filters: retrievalTraceFilters(options),
+          filters: retrievalTraceFilters(searchOptions),
           pipeline: "bm25",
           indexName: this.indexName,
         })
@@ -490,7 +514,8 @@ class GnoClientImpl implements GnoClient {
         this.decorateSearchResults(
           unwrapStore(
             await searchBm25(this.store, query, {
-              ...options,
+              ...searchOptions,
+              projectAffinity,
               traceSession: traceSession ?? undefined,
             })
           )
@@ -513,6 +538,11 @@ class GnoClientImpl implements GnoClient {
     let traceSession: RetrievalTraceSession | null = null;
 
     try {
+      const { projectHints, ...searchOptions } = options;
+      const projectAffinity = await resolveSdkProjectAffinity(
+        this.config,
+        projectHints
+      );
       const embedUri = resolveModelUri(
         this.config,
         "embed",
@@ -524,7 +554,7 @@ class GnoClientImpl implements GnoClient {
           store: this.store,
           config: this.config,
           query,
-          filters: retrievalTraceFilters(options),
+          filters: retrievalTraceFilters(searchOptions),
           pipeline: "vector",
           indexName: this.indexName,
           modelUris: [embedUri],
@@ -564,7 +594,11 @@ class GnoClientImpl implements GnoClient {
               },
               query,
               new Float32Array(queryEmbedResult.value),
-              { ...options, traceSession: traceSession ?? undefined }
+              {
+                ...searchOptions,
+                projectAffinity,
+                traceSession: traceSession ?? undefined,
+              }
             )
           )
         ),
@@ -628,12 +662,17 @@ class GnoClientImpl implements GnoClient {
     let traceSession: RetrievalTraceSession | null = null;
 
     try {
+      const { projectHints, ...queryOptions } = options;
+      const projectAffinity = await resolveSdkProjectAffinity(
+        this.config,
+        projectHints
+      );
       traceSession = unwrapStore(
         await startRetrievalTraceRequest({
           store: this.store,
           config: this.config,
           query,
-          filters: retrievalTraceFilters(options),
+          filters: retrievalTraceFilters(queryOptions),
           pipeline: "hybrid",
           indexName: this.indexName,
           modelUris: [embedUri, expandUri, rerankUri].filter(
@@ -664,7 +703,11 @@ class GnoClientImpl implements GnoClient {
                 rerankPort: ports.rerankPort,
               },
               query,
-              { ...options, traceSession: traceSession ?? undefined }
+              {
+                ...queryOptions,
+                projectAffinity,
+                traceSession: traceSession ?? undefined,
+              }
             )
           )
         ),
@@ -739,12 +782,17 @@ class GnoClientImpl implements GnoClient {
     let traceSession: RetrievalTraceSession | null = null;
 
     try {
+      const { projectHints, ...askOptions } = options;
+      const projectAffinity = await resolveSdkProjectAffinity(
+        this.config,
+        projectHints
+      );
       traceSession = unwrapStore(
         await startRetrievalTraceRequest({
           store: this.store,
           config: this.config,
           query,
-          filters: retrievalTraceFilters(options),
+          filters: retrievalTraceFilters(askOptions),
           pipeline: "ask",
           indexName: this.indexName,
           modelUris: [embedUri, expandUri, answerUri, rerankUri].filter(
@@ -777,16 +825,21 @@ class GnoClientImpl implements GnoClient {
       }
 
       if (verificationRequested && ports.answerPort) {
-        const verified = await buildVerifiedAsk(query, options, {
-          store: this.store,
-          config: this.config,
-          indexName: this.indexName,
-          vectorIndex: ports.vectorIndex,
-          embedPort: ports.embedPort,
-          rerankPort: ports.rerankPort,
-          genPort: ports.answerPort,
-          traceSession: traceSession ?? undefined,
-        });
+        const verified = await buildVerifiedAsk(
+          query,
+          { ...askOptions, projectAffinity },
+          {
+            store: this.store,
+            config: this.config,
+            indexName: this.indexName,
+            vectorIndex: ports.vectorIndex,
+            embedPort: ports.embedPort,
+            rerankPort: ports.rerankPort,
+            genPort: ports.answerPort,
+            projectAffinity,
+            traceSession: traceSession ?? undefined,
+          }
+        );
         if (traceSession) {
           unwrapStore(
             await traceSession.finish(
@@ -831,6 +884,7 @@ class GnoClientImpl implements GnoClient {
             noRerank: options.noRerank,
             candidateLimit: options.candidateLimit,
             queryLanguageHint: options.queryLanguageHint,
+            projectAffinity,
             traceSession: traceSession ?? undefined,
           }
         )
@@ -918,8 +972,9 @@ class GnoClientImpl implements GnoClient {
 
   async context(input: GnoContextInput): Promise<GnoContextResult> {
     this.assertOpen();
+    const { projectHints, ...contextInput } = input;
     validateContextCapsuleBuildInput(
-      { ...input, indexName: this.indexName },
+      { ...contextInput, indexName: this.indexName },
       this.indexName,
       this.config.collections.map((collection) => collection.name)
     );
@@ -935,6 +990,10 @@ class GnoClientImpl implements GnoClient {
     let ports: RuntimePorts | null = null;
     let traceSession: RetrievalTraceSession | null = null;
     try {
+      const projectAffinity = await resolveSdkProjectAffinity(
+        this.config,
+        projectHints
+      );
       traceSession = unwrapStore(
         await startRetrievalTraceRequest({
           store: this.store,
@@ -968,7 +1027,7 @@ class GnoClientImpl implements GnoClient {
         collection,
       });
       const capsule = await buildContextCapsule(
-        { ...input, indexName: this.indexName },
+        { ...contextInput, indexName: this.indexName },
         {
           store: this.store,
           config: this.config,
@@ -976,6 +1035,7 @@ class GnoClientImpl implements GnoClient {
           vectorIndex: ports.vectorIndex,
           embedPort: ports.embedPort,
           rerankPort: ports.rerankPort,
+          projectAffinity,
           traceSession: traceSession ?? undefined,
         }
       );

package/src/sdk/index.ts

@@ -51,6 +51,8 @@ export type {
   GnoMultiGetOptions,
   GnoMultiGetResult,
   GnoQueryOptions,
+  GnoProjectHintOptions,
+  GnoSearchOptions,
   GnoSkippedDocument,
   GnoUpdateOptions,
   GnoVectorSearchOptions,

package/src/sdk/types.ts

@@ -97,13 +97,26 @@ export interface GnoModelOverrides {
   rerankModel?: string;
 }
 
-export type GnoQueryOptions = HybridSearchOptions & GnoModelOverrides;
-export type GnoAskOptions = AskOptions & GnoModelOverrides;
-export type GnoVectorSearchOptions = SearchOptions & {
-  model?: string;
-};
+export interface GnoProjectHintOptions {
+  /** Opaque caller project hints; never resolved against the server filesystem. */
+  projectHints?: string[];
+}
+
+export type GnoSearchOptions = Omit<SearchOptions, "projectAffinity"> &
+  GnoProjectHintOptions;
+export type GnoQueryOptions = Omit<HybridSearchOptions, "projectAffinity"> &
+  GnoModelOverrides &
+  GnoProjectHintOptions;
+export type GnoAskOptions = Omit<AskOptions, "projectAffinity"> &
+  GnoModelOverrides &
+  GnoProjectHintOptions;
+export type GnoVectorSearchOptions = Omit<SearchOptions, "projectAffinity"> &
+  GnoProjectHintOptions & {
+    model?: string;
+  };
 
-export type GnoContextInput = Omit<ContextCapsuleBuildInput, "indexName">;
+export type GnoContextInput = Omit<ContextCapsuleBuildInput, "indexName"> &
+  GnoProjectHintOptions;
 export type GnoContextResult = ContextCapsuleV1;
 export type GnoContextVerificationResult = ContextCapsuleVerification;
 export type GnoContextErrorCode =
@@ -227,7 +240,7 @@ export interface GnoClient {
   readonly configPath: string | null;
   readonly configSource: "file" | "inline";
   isOpen(): boolean;
-  search(query: string, options?: SearchOptions): Promise<SearchResults>;
+  search(query: string, options?: GnoSearchOptions): Promise<SearchResults>;
   vsearch(
     query: string,
     options?: GnoVectorSearchOptions

package/src/serve/context-capsule.ts

@@ -21,6 +21,10 @@ import {
   parseContextVerifySurfaceInput,
 } from "../app/context-surface";
 import { ContextCapsuleContractError } from "../core/context-capsule";
+import {
+  ProjectAffinityInputError,
+  resolveRemoteProjectAffinity,
+} from "../core/project-affinity-surface";
 import { startRetrievalTraceRequest } from "../core/retrieval-trace-request";
 import { withRetrievalTraceHeader } from "./retrieval-trace";
 
@@ -85,7 +89,7 @@ export const handleContextBuild = async (
 ): Promise<Response> => {
   let traceSession: RetrievalTraceSession | null = null;
   try {
-    const { input, format } = parseContextBuildSurfaceInput(
+    const { input, format, projectHints } = parseContextBuildSurfaceInput(
       await parseJsonBody(request),
       context.indexName
     );
@@ -94,6 +98,18 @@ export const handleContextBuild = async (
       context.indexName,
       context.config.collections.map((collection) => collection.name)
     );
+    let projectAffinity;
+    try {
+      projectAffinity = await resolveRemoteProjectAffinity(
+        context.config,
+        projectHints
+      );
+    } catch (error) {
+      if (error instanceof ProjectAffinityInputError) {
+        throw new ContextCapsuleContractError("invalid_input", error.message);
+      }
+      throw error;
+    }
     const started = await startRetrievalTraceRequest({
       store: context.store,
       config: context.config,
@@ -137,6 +153,7 @@ export const handleContextBuild = async (
       vectorIndex: context.vectorIndex,
       embedPort: context.embedPort,
       rerankPort: context.rerankPort,
+      projectAffinity,
       traceSession: traceSession ?? undefined,
     });
     const finished = await traceSession?.finish(