@gmickel/gno 1.17.0 → 1.19.0

package/src/mcp/tools/workspace-write.ts

@@ -27,6 +27,7 @@ import {
   planMoveRefactor,
   planRenameRefactor,
 } from "../../core/file-refactors";
+import { recordContentMutation } from "../../core/mutation-generations";
 import { defaultSyncService, withContentTypeRules } from "../../ingestion";
 import { runTool, type ToolResult } from "./index";
 
@@ -210,11 +211,12 @@ export function handleRenameNote(
         const currentPath = join(collection.path, doc.relPath);
         const nextPath = join(collection.path, plan.nextRelPath);
         await renameFilePath(currentPath, nextPath);
-        await defaultSyncService.syncCollection(
+        const syncResult = await defaultSyncService.syncCollection(
           collection,
           ctx.store,
           withContentTypeRules({ runUpdateCmd: false }, ctx.config)
         );
+        recordContentMutation(syncResult, ctx.markContentMutation);
         return {
           uri: plan.nextUri,
           relPath: plan.nextRelPath,
@@ -255,11 +257,12 @@ export function handleMoveNote(
         const nextPath = join(collection.path, plan.nextRelPath);
         await mkdir(dirname(nextPath), { recursive: true });
         await renameFilePath(currentPath, nextPath);
-        await defaultSyncService.syncCollection(
+        const syncResult = await defaultSyncService.syncCollection(
           collection,
           ctx.store,
           withContentTypeRules({ runUpdateCmd: false }, ctx.config)
         );
+        recordContentMutation(syncResult, ctx.markContentMutation);
         return {
           uri: plan.nextUri,
           relPath: plan.nextRelPath,
@@ -308,11 +311,12 @@ export function handleDuplicateNote(
         const nextPath = join(collection.path, plan.nextRelPath);
         await mkdir(dirname(nextPath), { recursive: true });
         await copyFilePath(currentPath, nextPath);
-        await defaultSyncService.syncCollection(
+        const syncResult = await defaultSyncService.syncCollection(
           collection,
           ctx.store,
           withContentTypeRules({ runUpdateCmd: false }, ctx.config)
         );
+        recordContentMutation(syncResult, ctx.markContentMutation);
         return {
           uri: plan.nextUri,
           relPath: plan.nextRelPath,

package/src/pipeline/answer.ts

@@ -5,6 +5,7 @@
  * @module src/pipeline/answer
  */
 
+import type { RetrievalTraceSession } from "../core/retrieval-trace-session";
 import type { GenerationPort } from "../llm/types";
 import type { StorePort } from "../store/types";
 import type {
@@ -15,6 +16,11 @@ import type {
 } from "./types";
 
 import { buildAnswerPrompt, type AnswerPromptSource } from "./answer-prompt";
+import { attachCitationTraceMetadata } from "./trace-metadata";
+import {
+  CITATION_TRACE_METADATA,
+  SEARCH_RESULT_PLANNER_METADATA,
+} from "./types";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Constants
@@ -24,6 +30,11 @@ import { buildAnswerPrompt, type AnswerPromptSource } from "./answer-prompt";
 export const ABSTENTION_MESSAGE =
   "I don't have enough information in the provided sources to answer this question.";
 
+export const answerTraceTerminalStatus = (
+  citations: readonly Citation[] | undefined
+): "completed" | "partial" =>
+  citations && citations.length > 0 ? "completed" : "partial";
+
 /** Max characters per document (~8K tokens) */
 const MAX_DOC_CHARS = 32_000;
 
@@ -86,6 +97,65 @@ interface SelectedSource {
   reason: string;
 }
 
+interface ExactAnswerPassage {
+  text: string;
+  startLine: number;
+  endLine: number;
+  passageHash: string;
+}
+
+const sha256 = (value: string): string =>
+  new Bun.CryptoHasher("sha256").update(value).digest("hex");
+
+const completeLinePrefix = (
+  content: string,
+  startLine: number,
+  maxChars: number
+): ExactAnswerPassage | null => {
+  const lines = content.split("\n");
+  if (lines.length === 0) return null;
+  const selected: string[] = [];
+  let characters = 0;
+  for (const line of lines) {
+    const addition = selected.length === 0 ? line.length : line.length + 1;
+    if (characters + addition > maxChars) break;
+    selected.push(line);
+    characters += addition;
+  }
+  if (selected.length === 0) return null;
+  const text = selected.join("\n");
+  if (!text.trim()) return null;
+  return {
+    text,
+    startLine,
+    endLine: startLine + selected.length - 1,
+    passageHash: sha256(text),
+  };
+};
+
+const anchoredCompleteLines = (
+  content: string,
+  metadata: SearchResult[typeof SEARCH_RESULT_PLANNER_METADATA]
+): ExactAnswerPassage | null => {
+  if (
+    !metadata?.passageHash ||
+    metadata.startLine === undefined ||
+    metadata.endLine === undefined ||
+    metadata.endLine < metadata.startLine
+  ) {
+    return null;
+  }
+  const lines = content.split("\n");
+  const text = lines.slice(metadata.startLine - 1, metadata.endLine).join("\n");
+  if (
+    text.split("\n").length !== metadata.endLine - metadata.startLine + 1 ||
+    sha256(text) !== metadata.passageHash
+  ) {
+    return null;
+  }
+  return completeLinePrefix(text, metadata.startLine, MAX_DOC_CHARS);
+};
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Citation Processing
 // ─────────────────────────────────────────────────────────────────────────────
@@ -423,53 +493,78 @@ export async function generateGroundedAnswer(
 ): Promise<AnswerGenerationResult | null> {
   const { genPort, store } = deps;
   const sourceSelection = selectAdaptiveSources(query, results);
+  const finalRanks = new Map(
+    results.map((result, index) => [result, index + 1] as const)
+  );
   const promptSources: AnswerPromptSource[] = [];
   const citations: Citation[] = [];
   let citationIndex = 0;
 
   for (const r of sourceSelection.selected) {
-    let content: string | null = null;
-    let usedFullContent = false;
+    let passage: ExactAnswerPassage | null = null;
+    const plannerMetadata = r[SEARCH_RESULT_PLANNER_METADATA];
+    const sourceHash = r.source.sourceHash;
+    const mirrorHash = r.conversion?.mirrorHash;
 
     // Try to fetch full document content if store available
-    if (store && r.conversion?.mirrorHash) {
-      const contentResult = await store.getContent(r.conversion.mirrorHash);
+    if (store && mirrorHash) {
+      const contentResult = await store.getContent(mirrorHash);
       if (contentResult.ok && contentResult.value) {
-        content = contentResult.value;
-        usedFullContent = true;
-        // Truncate to max doc chars
-        if (content.length > MAX_DOC_CHARS) {
-          content = `${content.slice(0, MAX_DOC_CHARS)}\n\n[... truncated ...]`;
+        if (sha256(contentResult.value) === mirrorHash) {
+          passage =
+            anchoredCompleteLines(contentResult.value, plannerMetadata) ??
+            completeLinePrefix(contentResult.value, 1, MAX_DOC_CHARS);
         }
       }
     }
 
-    // Fallback to snippet if full content unavailable
-    if (!content) {
-      if (!r.snippet || r.snippet.trim().length === 0) {
-        continue;
-      }
-      content =
-        r.snippet.length > MAX_SNIPPET_CHARS
-          ? `${r.snippet.slice(0, MAX_SNIPPET_CHARS)}...`
-          : r.snippet;
+    // Snippet fallback is allowed only when the planner proves it is the exact
+    // complete canonical chunk, never an FTS marker/ellipsis presentation.
+    if (
+      !passage &&
+      plannerMetadata?.passageHash &&
+      plannerMetadata.startLine !== undefined &&
+      plannerMetadata.endLine !== undefined &&
+      sha256(r.snippet) === plannerMetadata.passageHash &&
+      r.snippet.split("\n").length ===
+        plannerMetadata.endLine - plannerMetadata.startLine + 1
+    ) {
+      passage = completeLinePrefix(
+        r.snippet,
+        plannerMetadata.startLine,
+        MAX_SNIPPET_CHARS
+      );
     }
+    if (!(passage && sourceHash && mirrorHash)) continue;
 
     citationIndex += 1;
     promptSources.push({
       index: citationIndex,
       docid: r.docid,
       uri: r.uri,
-      content,
+      content: passage.text,
       guidance: r.context,
     });
-    // Clear line range when citing full content (not a specific snippet)
-    citations.push({
-      docid: r.docid,
-      uri: r.uri,
-      startLine: usedFullContent ? undefined : r.snippetRange?.startLine,
-      endLine: usedFullContent ? undefined : r.snippetRange?.endLine,
-    });
+    citations.push(
+      attachCitationTraceMetadata(
+        {
+          docid: r.docid,
+          uri: r.uri,
+          startLine: passage.startLine,
+          endLine: passage.endLine,
+        },
+        {
+          sourceHash,
+          mirrorHash,
+          passageHash: passage.passageHash,
+          seq: plannerMetadata?.seq,
+          rank: finalRanks.get(r) ?? 1,
+          plannerRank: plannerMetadata?.retrievalRank,
+          sources: plannerMetadata?.sources,
+          graphExpanded: plannerMetadata?.graphExpanded,
+        }
+      )
+    );
   }
 
   if (promptSources.length === 0) {
@@ -528,3 +623,49 @@ export function processAnswerResult(rawResult: AnswerGenerationResult): {
     answerContext: rawResult.answerContext,
   };
 }
+
+/** Process first, then record only citations retained in the final answer. */
+export async function processAnswerResultWithTrace(
+  rawResult: AnswerGenerationResult,
+  traceSession?: RetrievalTraceSession
+): Promise<ReturnType<typeof processAnswerResult>> {
+  const processed = processAnswerResult(rawResult);
+  if (!traceSession || processed.citations.length === 0) return processed;
+  const evidence = processed.citations.flatMap((citation) => {
+    const metadata = citation[CITATION_TRACE_METADATA];
+    if (
+      !metadata ||
+      citation.startLine === undefined ||
+      citation.endLine === undefined
+    ) {
+      return [];
+    }
+    return [
+      {
+        docid: citation.docid,
+        uri: citation.uri,
+        sourceHash: metadata.sourceHash,
+        mirrorHash: metadata.mirrorHash,
+        passageHash: metadata.passageHash,
+        startLine: citation.startLine,
+        endLine: citation.endLine,
+        rank: metadata.rank,
+        ...(metadata.seq === undefined ? {} : { seq: metadata.seq }),
+        ...(metadata.plannerRank === undefined
+          ? {}
+          : { plannerRank: metadata.plannerRank }),
+        ...(metadata.sources === undefined
+          ? {}
+          : { sources: metadata.sources }),
+        ...(metadata.graphExpanded === undefined
+          ? {}
+          : { graphExpanded: metadata.graphExpanded }),
+      },
+    ];
+  });
+  const recorded = await traceSession.recordEvidence("cite", evidence);
+  if (!recorded.ok) {
+    throw new Error(`Trace recording failed: ${recorded.error.message}`);
+  }
+  return processed;
+}

package/src/pipeline/graph-retrieval.ts

@@ -62,6 +62,7 @@ const matchesDocumentFilters = (
     until?: string;
     categories?: string[];
     author?: string;
+    relPathPrefix?: string;
   }
 ): boolean => {
   if (
@@ -201,6 +202,7 @@ export async function expandGraphCandidates(
     until?: string;
     categories?: string[];
     author?: string;
+    relPathPrefix?: string;
   } = {}
 ): Promise<GraphRetrievalResult> {
   const maxCandidates = Math.max(
@@ -249,6 +251,13 @@ export async function expandGraphCandidates(
     if (!doc.mirrorHash) {
       continue;
     }
+    if (
+      options.relPathPrefix !== undefined &&
+      doc.relPath !== options.relPathPrefix &&
+      !doc.relPath.startsWith(`${options.relPathPrefix}/`)
+    ) {
+      continue;
+    }
     const rank =
       seedCandidates.findIndex(
         (candidate) => candidate.mirrorHash === doc.mirrorHash
@@ -325,7 +334,12 @@ export async function expandGraphCandidates(
   }
 
   const metadataFilteredDocs = docsResult.value.filter(
-    (doc) => doc.mirrorHash && matchesDocumentFilters(doc, options)
+    (doc) =>
+      doc.mirrorHash &&
+      (options.relPathPrefix === undefined ||
+        doc.relPath === options.relPathPrefix ||
+        doc.relPath.startsWith(`${options.relPathPrefix}/`)) &&
+      matchesDocumentFilters(doc, options)
   );
   const docs = await filterDocsByTags(store, metadataFilteredDocs, options);
   const docByDocid = new Map(docs.map((doc) => [doc.docid, doc]));

package/src/pipeline/hybrid.ts

@@ -55,9 +55,10 @@ import {
   shouldSortByRecency,
 } from "./temporal";
 import {
-  DEFAULT_PIPELINE_CONFIG,
-  SEARCH_RESULT_PLANNER_METADATA,
-} from "./types";
+  attachSearchResultPlannerMetadata,
+  attachSearchResultsTraceMetadata,
+} from "./trace-metadata";
+import { DEFAULT_PIPELINE_CONFIG } from "./types";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Dependencies
@@ -121,11 +122,13 @@ async function checkBm25Strength(
     until?: string;
     categories?: string[];
     author?: string;
+    relPathPrefix?: string;
   }
 ): Promise<boolean> {
   const result = await store.searchFts(query, {
     limit: 5,
     collection: options?.collection,
+    relPathPrefix: options?.relPathPrefix,
     language: options?.lang,
     tagsAll: options?.tagsAll,
     tagsAny: options?.tagsAny,
@@ -179,11 +182,13 @@ async function searchFtsChunks(
     until?: string;
     categories?: string[];
     author?: string;
+    relPathPrefix?: string;
   }
 ): Promise<FtsChunksResult> {
   const result = await store.searchFts(query, {
     limit: options.limit,
     collection: options.collection,
+    relPathPrefix: options.relPathPrefix,
     language: options.lang,
     tagsAll: options.tagsAll,
     tagsAny: options.tagsAny,
@@ -216,7 +221,11 @@ async function searchVectorChunks(
   vectorIndex: VectorIndexPort,
   embedPort: EmbeddingPort,
   query: string,
-  options: { limit: number; minScore?: number }
+  options: {
+    limit: number;
+    minScore?: number;
+    allowedMirrorHashes?: string[];
+  }
 ): Promise<ChunkId[]> {
   if (!vectorIndex.searchAvailable) {
     return [];
@@ -234,7 +243,10 @@ async function searchVectorChunks(
   const searchResult = await vectorIndex.searchNearest(
     queryEmbedding,
     options.limit,
-    { minScore: options.minScore }
+    {
+      minScore: options.minScore,
+      allowedMirrorHashes: options.allowedMirrorHashes,
+    }
   );
 
   if (!searchResult.ok) {
@@ -381,6 +393,7 @@ export async function searchHybrid(
           until: temporalRange.until,
           categories: options.categories,
           author: options.author,
+          relPathPrefix: options.retrievalScope?.relPathPrefix,
         });
 
     if (hasStrongSignal) {
@@ -397,6 +410,8 @@ export async function searchHybrid(
       });
       if (expandResult.ok) {
         expansion = expandResult.value;
+      } else {
+        counters.fallbackEvents.push("expansion_error");
       }
     }
   }
@@ -428,6 +443,7 @@ export async function searchHybrid(
     until: temporalRange.until,
     categories: options.categories,
     author: options.author,
+    relPathPrefix: options.retrievalScope?.relPathPrefix,
   });
 
   // Propagate FTS syntax errors as INVALID_INPUT
@@ -462,6 +478,7 @@ export async function searchHybrid(
           until: temporalRange.until,
           categories: options.categories,
           author: options.author,
+          relPathPrefix: options.retrievalScope?.relPathPrefix,
         })
       )
     );
@@ -509,6 +526,7 @@ export async function searchHybrid(
         query,
         {
           limit: limit * 2 * retrievalMultiplier,
+          allowedMirrorHashes: options.retrievalScope?.allowedMirrorHashes,
         }
       );
 
@@ -552,7 +570,10 @@ export async function searchHybrid(
 
           const searchResult = await vectorIndex.searchNearest(
             new Float32Array(embedding),
-            variant.limit
+            variant.limit,
+            {
+              allowedMirrorHashes: options.retrievalScope?.allowedMirrorHashes,
+            }
           );
           if (!searchResult.ok || searchResult.value.length === 0) {
             continue;
@@ -615,6 +636,7 @@ export async function searchHybrid(
     limit,
     candidateLimit,
     disabled: !options.graph || options.noGraph,
+    relPathPrefix: options.retrievalScope?.relPathPrefix,
     lang: options.lang,
     tagsAll: options.tagsAll,
     tagsAny: options.tagsAny,
@@ -735,6 +757,14 @@ export async function searchHybrid(
   const matchesMetadataFilters = (
     doc: (typeof docsResult.value)[number]
   ): boolean => {
+    const relPathPrefix = options.retrievalScope?.relPathPrefix;
+    if (
+      relPathPrefix !== undefined &&
+      doc.relPath !== relPathPrefix &&
+      !doc.relPath.startsWith(`${relPathPrefix}/`)
+    ) {
+      return false;
+    }
     if (!isWithinTemporalRange(doc.sourceMtime, temporalRange)) {
       return false;
     }
@@ -923,42 +953,51 @@ export async function searchHybrid(
       if (!docidMap.has(docidKey)) docidMap.set(docidKey, doc.docid);
       const collectionPath = collectionPaths.get(doc.collection);
       seenDocids.add(doc.docid);
-      results.push({
-        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,
-        },
-        [SEARCH_RESULT_PLANNER_METADATA]: {
-          retrievalRank: candidateIndex + 1,
-          mirrorHash: candidate.mirrorHash,
-          seq: snippetChunk.seq,
-          sources: [...candidate.sources].sort(),
-          graphExpanded: candidate.sources.includes("graph"),
-        },
-      });
+      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,
+            },
+          },
+          {
+            retrievalRank: candidateIndex + 1,
+            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"),
+          }
+        )
+      );
     }
   }
   timings.assemblyMs = performance.now() - assemblyStartedAt;
@@ -1002,7 +1041,7 @@ export async function searchHybrid(
   const finalResults = results.slice(0, limit);
   await attachSearchResultContexts(store, finalResults);
 
-  return ok({
+  const output: SearchResults = {
     results: finalResults,
     meta: {
       query,
@@ -1033,5 +1072,74 @@ export async function searchHybrid(
       explain: explainData,
       trace: diagnoseTrace,
     },
+  };
+  const fallbackCodes = [...new Set(counters.fallbackEvents)].sort();
+  const capabilityOutcomes = [
+    { capability: "lexical_search", status: "used" as const },
+    vectorAvailable
+      ? fallbackCodes.includes("vector_embed_error")
+        ? {
+            capability: "semantic_search",
+            status: "failed" as const,
+            reasonCode: "vector_embed_error",
+          }
+        : { capability: "semantic_search", status: "used" as const }
+      : {
+          capability: "semantic_search",
+          status: "unavailable" as const,
+          reasonCode: "vector_unavailable",
+        },
+    expansion !== null
+      ? { capability: "query_expansion", status: "used" as const }
+      : {
+          capability: "query_expansion",
+          status:
+            expansionStatus === "attempted"
+              ? ("failed" as const)
+              : ("unavailable" as const),
+          reasonCode:
+            expansionStatus === "attempted"
+              ? "expansion_error"
+              : expansionStatus === "skipped_strong"
+                ? "expansion_skipped_strong"
+                : "expansion_disabled",
+        },
+    rerankResult.reranked
+      ? { capability: "reranking", status: "used" as const }
+      : {
+          capability: "reranking",
+          status:
+            rerankResult.fallbackReason === "error"
+              ? ("failed" as const)
+              : ("unavailable" as const),
+          reasonCode:
+            rerankResult.fallbackReason === "error"
+              ? "rerank_error"
+              : "rerank_disabled",
+        },
+    graphExpansion.meta.enabled
+      ? { capability: "graph_expansion", status: "used" as const }
+      : {
+          capability: "graph_expansion",
+          status: "unavailable" as const,
+          reasonCode:
+            graphExpansion.meta.fallbackReasons[0] ?? "graph_disabled",
+        },
+  ];
+  attachSearchResultsTraceMetadata(output, {
+    capabilityOutcomes,
+    fallbackCodes,
   });
+  const traceResult = await options.traceSession?.recordRetrieval(
+    output,
+    timings.totalMs
+  );
+  if (traceResult && !traceResult.ok) {
+    return err(
+      "QUERY_FAILED",
+      `Trace recording failed: ${traceResult.error.message}`,
+      traceResult.error.cause
+    );
+  }
+  return ok(output);
 }