@gmickel/gno 1.17.0 → 1.19.0

package/src/pipeline/search.ts

@@ -27,6 +27,8 @@ import {
   resolveTemporalRange,
   shouldSortByRecency,
 } from "./temporal";
+import { attachSearchResultPlannerMetadata } from "./trace-metadata";
+import { SEARCH_RESULT_PLANNER_METADATA } from "./types";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Score Normalization
@@ -113,7 +115,7 @@ function buildSearchResult(ctx: BuildResultContext): SearchResult {
       : undefined;
   }
 
-  return {
+  const result: SearchResult = {
     docid: fts.docid ?? "",
     score: fts.score, // Raw score, normalized later as batch
     uri: fts.uri ?? "",
@@ -127,6 +129,19 @@ function buildSearchResult(ctx: BuildResultContext): SearchResult {
     source,
     conversion: fts.mirrorHash ? { mirrorHash: fts.mirrorHash } : undefined,
   };
+  if (!(chunk && fts.mirrorHash)) return result;
+  return attachSearchResultPlannerMetadata(result, {
+    retrievalRank: 0,
+    mirrorHash: fts.mirrorHash,
+    seq: chunk.seq,
+    sources: ["bm25"],
+    graphExpanded: false,
+    startLine: chunk.startLine,
+    endLine: chunk.endLine,
+    passageHash: new Bun.CryptoHasher("sha256")
+      .update(chunk.text)
+      .digest("hex"),
+  });
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -142,6 +157,7 @@ export async function searchBm25(
   query: string,
   options: SearchOptions = {}
 ): Promise<ReturnType<typeof ok<SearchResults>>> {
+  const traceStartedAt = options.traceSession ? performance.now() : 0;
   const limit = options.limit ?? 20;
   const minScore = options.minScore ?? 0;
   const recencySort = shouldSortByRecency(query);
@@ -161,6 +177,7 @@ export async function searchBm25(
   const ftsResult = await store.searchFts(query, {
     limit: retrievalLimit,
     collection: options.collection,
+    relPathPrefix: options.retrievalScope?.relPathPrefix,
     language: options.lang,
     snippet: !(options.full || options.lineNumbers),
     tagsAll: options.tagsAll,
@@ -331,9 +348,13 @@ export async function searchBm25(
   }
 
   const finalResults = filteredResults.slice(0, limit);
+  for (const [index, result] of finalResults.entries()) {
+    const metadata = result[SEARCH_RESULT_PLANNER_METADATA];
+    if (metadata) metadata.retrievalRank = index + 1;
+  }
   await attachSearchResultContexts(store, finalResults);
 
-  return ok({
+  const output: SearchResults = {
     results: finalResults,
     meta: {
       query,
@@ -349,5 +370,17 @@ export async function searchBm25(
       author: options.author,
       queryLanguage,
     },
-  });
+  };
+  const traceResult = await options.traceSession?.recordRetrieval(
+    output,
+    performance.now() - traceStartedAt
+  );
+  if (traceResult && !traceResult.ok) {
+    return err(
+      "QUERY_FAILED",
+      `Trace recording failed: ${traceResult.error.message}`,
+      traceResult.error.cause
+    );
+  }
+  return ok(output);
 }

package/src/pipeline/trace-metadata.ts

@@ -0,0 +1,47 @@
+/** Non-canonical retrieval metadata attached without changing public payloads. */
+
+import type {
+  Citation,
+  CitationTraceMetadata,
+  SearchResult,
+  SearchResultPlannerMetadata,
+  SearchResults,
+  SearchResultsTraceMetadata,
+} from "./types";
+
+import {
+  CITATION_TRACE_METADATA,
+  SEARCH_RESULT_PLANNER_METADATA,
+  SEARCH_RESULTS_TRACE_METADATA,
+} from "./types";
+
+const attachHiddenMetadata = <Value extends object, Metadata>(
+  value: Value,
+  key: symbol,
+  metadata: Metadata
+): Value => {
+  Object.defineProperty(value, key, {
+    configurable: false,
+    enumerable: false,
+    value: metadata,
+    writable: false,
+  });
+  return value;
+};
+
+export const attachSearchResultPlannerMetadata = <Result extends SearchResult>(
+  result: Result,
+  metadata: SearchResultPlannerMetadata
+): Result =>
+  attachHiddenMetadata(result, SEARCH_RESULT_PLANNER_METADATA, metadata);
+
+export const attachCitationTraceMetadata = <Result extends Citation>(
+  citation: Result,
+  metadata: CitationTraceMetadata
+): Result => attachHiddenMetadata(citation, CITATION_TRACE_METADATA, metadata);
+
+export const attachSearchResultsTraceMetadata = <Result extends SearchResults>(
+  results: Result,
+  metadata: SearchResultsTraceMetadata
+): Result =>
+  attachHiddenMetadata(results, SEARCH_RESULTS_TRACE_METADATA, metadata);

package/src/pipeline/types.ts

@@ -5,6 +5,7 @@
  * @module src/pipeline/types
  */
 
+import type { RetrievalTraceSession } from "../core/retrieval-trace-session";
 import type { StoreResult } from "../store/types";
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -48,6 +49,11 @@ export interface SearchResultPlannerMetadata {
   seq: number;
   sources: FusionSource[];
   graphExpanded: boolean;
+  /** Exact canonical chunk coordinates, retained even for full-content output. */
+  startLine?: number;
+  endLine?: number;
+  /** SHA-256 of the complete canonical chunk lines. */
+  passageHash?: string;
 }
 
 /** Single search result matching output schema */
@@ -122,10 +128,26 @@ export interface SearchMeta {
   trace?: QueryDiagnoseTrace;
 }
 
+export const SEARCH_RESULTS_TRACE_METADATA = Symbol(
+  "gno.searchResultsTraceMetadata"
+);
+
+export interface SearchCapabilityOutcome {
+  capability: string;
+  status: "attempted" | "used" | "unavailable" | "failed";
+  reasonCode?: string;
+}
+
+export interface SearchResultsTraceMetadata {
+  capabilityOutcomes: SearchCapabilityOutcome[];
+  fallbackCodes: string[];
+}
+
 /** Complete search results wrapper */
 export interface SearchResults {
   results: SearchResult[];
   meta: SearchMeta;
+  [SEARCH_RESULTS_TRACE_METADATA]?: SearchResultsTraceMetadata;
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -134,12 +156,19 @@ export interface SearchResults {
 
 /** Common options for all search commands */
 export interface SearchOptions {
+  /** Internal receipt seam; never serialized or included in public schemas. */
+  traceSession?: RetrievalTraceSession;
   /** Max results */
   limit?: number;
   /** Min score threshold (0-1) */
   minScore?: number;
   /** Filter by collection */
   collection?: string;
+  /** Internal exact corpus scope used by deterministic retrieval replay. */
+  retrievalScope?: {
+    relPathPrefix?: string;
+    allowedMirrorHashes: string[];
+  };
   /** Language filter/hint (BCP-47) */
   lang?: string;
   /** Include full content instead of snippet */
@@ -357,11 +386,25 @@ export const DEFAULT_PIPELINE_CONFIG: PipelineConfig = {
 // ─────────────────────────────────────────────────────────────────────────────
 
 /** Citation reference */
+export const CITATION_TRACE_METADATA = Symbol("gno.citationTraceMetadata");
+
+export interface CitationTraceMetadata {
+  sourceHash: string;
+  mirrorHash: string;
+  passageHash: string;
+  seq?: number;
+  rank: number;
+  plannerRank?: number;
+  sources?: FusionSource[];
+  graphExpanded?: boolean;
+}
+
 export interface Citation {
   docid: string;
   uri: string;
   startLine?: number;
   endLine?: number;
+  [CITATION_TRACE_METADATA]?: CitationTraceMetadata;
 }
 
 /** Source selection entry for answer-generation explain */

package/src/pipeline/vsearch.ts

@@ -26,6 +26,8 @@ import {
   shouldSortByRecency,
   type TemporalRange,
 } from "./temporal";
+import { attachSearchResultPlannerMetadata } from "./trace-metadata";
+import { SEARCH_RESULT_PLANNER_METADATA } from "./types";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Score Normalization
@@ -76,6 +78,7 @@ export async function searchVectorWithEmbedding(
   queryEmbedding: Float32Array,
   options: SearchOptions = {}
 ): Promise<ReturnType<typeof ok<SearchResults>>> {
+  const traceStartedAt = options.traceSession ? performance.now() : 0;
   const { store, vectorIndex } = deps;
   const limit = options.limit ?? 20;
   const minScore = options.minScore ?? 0;
@@ -102,6 +105,7 @@ export async function searchVectorWithEmbedding(
     retrievalLimit,
     {
       minScore,
+      allowedMirrorHashes: options.retrievalScope?.allowedMirrorHashes,
     }
   );
 
@@ -124,6 +128,7 @@ export async function searchVectorWithEmbedding(
   // Cache docs to avoid N+1 queries (filtered by collection and tags)
   const docByMirrorHash = await buildDocumentMap(store, {
     collection: options.collection,
+    relPathPrefix: options.retrievalScope?.relPathPrefix,
     tagsAll: options.tagsAll,
     tagsAny: options.tagsAny,
     since: temporalRange.since,
@@ -214,6 +219,7 @@ export async function searchVectorWithEmbedding(
             language: chunk.language,
             startLine: chunk.startLine,
             endLine: chunk.endLine,
+            seq: chunk.seq,
           },
           score,
         });
@@ -223,40 +229,56 @@ export async function searchVectorWithEmbedding(
 
     const collectionPath = collectionPaths.get(doc.collection);
 
-    results.push({
-      docid: doc.docid,
-      score,
-      uri: doc.uri,
-      title: doc.title ?? undefined,
-      contentType: doc.contentType ?? undefined,
-      categories: doc.categories ?? undefined,
-      line: chunk.startLine,
-      snippet: chunk.text,
-      snippetLanguage: chunk.language ?? undefined,
-      snippetRange: {
-        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,
-    });
+    results.push(
+      attachSearchResultPlannerMetadata(
+        {
+          docid: doc.docid,
+          score,
+          uri: doc.uri,
+          title: doc.title ?? undefined,
+          contentType: doc.contentType ?? undefined,
+          categories: doc.categories ?? undefined,
+          line: chunk.startLine,
+          snippet: chunk.text,
+          snippetLanguage: chunk.language ?? undefined,
+          snippetRange: {
+            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,
+        },
+        {
+          retrievalRank: 0,
+          mirrorHash: vec.mirrorHash,
+          seq: chunk.seq,
+          sources: ["vector"],
+          graphExpanded: false,
+          startLine: chunk.startLine,
+          endLine: chunk.endLine,
+          passageHash: new Bun.CryptoHasher("sha256")
+            .update(chunk.text)
+            .digest("hex"),
+        }
+      )
+    );
   }
 
   // For --full, fetch full content and build results
@@ -279,7 +301,7 @@ export async function searchVectorWithEmbedding(
 
       const collectionPath = collectionPaths.get(doc.collection);
 
-      results.push({
+      const result: SearchResult = {
         docid: doc.docid,
         score,
         uri: doc.uri,
@@ -312,7 +334,23 @@ export async function searchVectorWithEmbedding(
               converterVersion: doc.converterVersion ?? undefined,
             }
           : undefined,
-      });
+      };
+      results.push(
+        doc.mirrorHash
+          ? attachSearchResultPlannerMetadata(result, {
+              retrievalRank: 0,
+              mirrorHash: doc.mirrorHash,
+              seq: chunk.seq,
+              sources: ["vector"],
+              graphExpanded: false,
+              startLine: chunk.startLine,
+              endLine: chunk.endLine,
+              passageHash: new Bun.CryptoHasher("sha256")
+                .update(chunk.text)
+                .digest("hex"),
+            })
+          : result
+      );
     }
   }
 
@@ -334,9 +372,13 @@ export async function searchVectorWithEmbedding(
   }
 
   const finalResults = results.slice(0, limit);
+  for (const [index, result] of finalResults.entries()) {
+    const metadata = result[SEARCH_RESULT_PLANNER_METADATA];
+    if (metadata) metadata.retrievalRank = index + 1;
+  }
   await attachSearchResultContexts(store, finalResults);
 
-  return ok({
+  const output: SearchResults = {
     results: finalResults,
     meta: {
       query,
@@ -353,7 +395,19 @@ export async function searchVectorWithEmbedding(
       author: options.author,
       queryLanguage,
     },
-  });
+  };
+  const traceResult = await options.traceSession?.recordRetrieval(
+    output,
+    performance.now() - traceStartedAt
+  );
+  if (traceResult && !traceResult.ok) {
+    return err(
+      "QUERY_FAILED",
+      `Trace recording failed: ${traceResult.error.message}`,
+      traceResult.error.cause
+    );
+  }
+  return ok(output);
 }
 
 /**
@@ -397,6 +451,7 @@ interface ChunkInfo {
   language: string | null;
   startLine: number;
   endLine: number;
+  seq: number;
 }
 
 interface DocumentInfo {
@@ -425,6 +480,7 @@ interface DocumentInfo {
 
 interface DocumentMapOptions {
   collection?: string;
+  relPathPrefix?: string;
   tagsAll?: string[];
   tagsAny?: string[];
   since?: string;
@@ -513,6 +569,13 @@ async function buildDocumentMap(
   }
 
   for (const doc of activeDocs) {
+    if (
+      options.relPathPrefix !== undefined &&
+      doc.relPath !== options.relPathPrefix &&
+      !doc.relPath.startsWith(`${options.relPathPrefix}/`)
+    ) {
+      continue;
+    }
     if (!isWithinTemporalRange(doc.sourceMtime, temporalRange)) {
       continue;
     }