@gmickel/gno 1.18.0 → 1.20.0

package/src/cli/commands/ask.ts

@@ -5,6 +5,8 @@
  * @module src/cli/commands/ask
  */
 
+import type { RetrievalTraceSurfaceMetadata } from "../../core/retrieval-trace-session";
+import type { RetrievalTraceSession } from "../../core/retrieval-trace-session";
 import type {
   EmbeddingPort,
   GenerationPort,
@@ -12,12 +14,19 @@ import type {
 } from "../../llm/types";
 import type { AskOptions, AskResult, Citation } from "../../pipeline/types";
 
+import { buildVerifiedAsk } from "../../app/verified-ask";
+import {
+  finishRetrievalTraceAfterError,
+  retrievalTraceFilters,
+  startRetrievalTraceRequest,
+} from "../../core/retrieval-trace-request";
 import { LlmAdapter } from "../../llm/nodeLlamaCpp/adapter";
 import { resolveDownloadPolicy } from "../../llm/policy";
 import { resolveModelUri } from "../../llm/registry";
 import {
+  answerTraceTerminalStatus,
   generateGroundedAnswer,
-  processAnswerResult,
+  processAnswerResultWithTrace,
 } from "../../pipeline/answer";
 import { type HybridSearchDeps, searchHybrid } from "../../pipeline/hybrid";
 import {
@@ -31,6 +40,8 @@ import {
 } from "../progress";
 import { initStore } from "./shared";
 
+export { formatAsk } from "./ask-format";
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Types
 // ─────────────────────────────────────────────────────────────────────────────
@@ -55,7 +66,11 @@ export type AskCommandOptions = AskOptions & {
 };
 
 export type AskCommandResult =
-  | { success: true; data: AskResult }
+  | {
+      success: true;
+      data: AskResult;
+      metadata?: RetrievalTraceSurfaceMetadata;
+    }
   | { success: false; error: string };
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -71,9 +86,11 @@ export async function ask(
   options: AskCommandOptions = {}
 ): Promise<AskCommandResult> {
   const limit = options.limit ?? 5;
+  const globals = getGlobals();
 
   const initResult = await initStore({
     configPath: options.configPath,
+    indexName: globals.index,
     collection: options.collection,
     syncConfig: false,
   });
@@ -88,12 +105,56 @@ export async function ask(
   let expandPort: GenerationPort | null = null;
   let answerPort: GenerationPort | null = null;
   let rerankPort: RerankPort | null = null;
+  let traceSession: RetrievalTraceSession | undefined;
 
   try {
+    const verificationRequested = options.verify === true;
+    const answerRequested =
+      verificationRequested || Boolean(options.answer && !options.noAnswer);
+    const embedUri = resolveModelUri(
+      config,
+      "embed",
+      options.embedModel,
+      options.collection
+    );
+    const expandUri =
+      !verificationRequested && !options.noExpand && !options.queryModes?.length
+        ? resolveModelUri(
+            config,
+            "expand",
+            options.expandModel ?? options.genModel,
+            options.collection
+          )
+        : undefined;
+    const answerUri = answerRequested
+      ? resolveModelUri(config, "gen", options.genModel, options.collection)
+      : undefined;
+    const rerankUri = !options.noRerank
+      ? resolveModelUri(
+          config,
+          "rerank",
+          options.rerankModel,
+          options.collection
+        )
+      : undefined;
+    const traceStart = await startRetrievalTraceRequest({
+      store,
+      config,
+      query,
+      filters: retrievalTraceFilters({ ...options, limit }),
+      pipeline: "ask",
+      indexName: globals.index,
+      modelUris: [embedUri, expandUri, answerUri, rerankUri].filter(
+        (value): value is string => Boolean(value)
+      ),
+    });
+    if (!traceStart.ok) {
+      return { success: false, error: traceStart.error.message };
+    }
+    traceSession = traceStart.value ?? undefined;
     const llm = new LlmAdapter(config);
 
     // Resolve download policy from env/flags
-    const globals = getGlobals();
     const policy = resolveDownloadPolicy(process.env, {
       offline: globals.offline,
     });
@@ -105,12 +166,6 @@ export async function ask(
       : undefined;
 
     // Create embedding port
-    const embedUri = resolveModelUri(
-      config,
-      "embed",
-      options.embedModel,
-      options.collection
-    );
     const embedResult = await llm.createEmbeddingPort(embedUri, {
       policy,
       onProgress: downloadProgress
@@ -122,13 +177,7 @@ export async function ask(
     }
 
     // Create expansion port when expansion is enabled.
-    if (!options.noExpand && !options.queryModes?.length) {
-      const expandUri = resolveModelUri(
-        config,
-        "expand",
-        options.expandModel ?? options.genModel,
-        options.collection
-      );
+    if (expandUri) {
       const genResult = await llm.createExpansionPort(expandUri, {
         policy,
         onProgress: downloadProgress
@@ -141,14 +190,8 @@ export async function ask(
     }
 
     // Create answer generation port when answers are requested.
-    if (options.answer) {
-      const genUri = resolveModelUri(
-        config,
-        "gen",
-        options.genModel,
-        options.collection
-      );
-      const genResult = await llm.createGenerationPort(genUri, {
+    if (answerUri) {
+      const genResult = await llm.createGenerationPort(answerUri, {
         policy,
         onProgress: downloadProgress
           ? (progress) => downloadProgress("gen", progress)
@@ -160,13 +203,7 @@ export async function ask(
     }
 
     // Create rerank port (unless --fast or --no-rerank)
-    if (!options.noRerank) {
-      const rerankUri = resolveModelUri(
-        config,
-        "rerank",
-        options.rerankModel,
-        options.collection
-      );
+    if (rerankUri) {
       const rerankResult = await llm.createRerankPort(rerankUri, {
         policy,
         onProgress: downloadProgress
@@ -208,12 +245,14 @@ export async function ask(
       expandPort,
       rerankPort,
     };
-
-    // Check if answer generation is explicitly requested
-    const answerRequested = options.answer && !options.noAnswer;
-
     // Fail early if --answer is requested but no generation model available
     if (answerRequested && answerPort === null) {
+      await traceSession?.recordCapability(
+        "answer_generation",
+        "unavailable",
+        "model_unavailable"
+      );
+      await traceSession?.finish("failed");
       return {
         success: false,
         error:
@@ -222,6 +261,34 @@ export async function ask(
       };
     }
 
+    if (verificationRequested && answerPort) {
+      const verified = await buildVerifiedAsk(
+        query,
+        { ...options, limit },
+        {
+          store,
+          config,
+          indexName: globals.index,
+          vectorIndex,
+          embedPort,
+          rerankPort,
+          genPort: answerPort,
+          traceSession,
+        }
+      );
+      const finalized = await traceSession?.finish(
+        answerTraceTerminalStatus(verified.citations)
+      );
+      if (finalized && !finalized.ok) {
+        return { success: false, error: finalized.error.message };
+      }
+      return {
+        success: true,
+        data: verified,
+        metadata: traceSession?.metadata(),
+      };
+    }
+
     // Run hybrid search
     const searchResult = await searchHybrid(deps, query, {
       limit,
@@ -235,13 +302,17 @@ export async function ask(
       tagsAll: options.tagsAll,
       tagsAny: options.tagsAny,
       exclude: options.exclude,
+      minScore: options.minScore,
+      graph: options.graph,
       queryModes: options.queryModes,
       noExpand: options.noExpand,
       noRerank: options.noRerank,
       candidateLimit: options.candidateLimit,
+      traceSession,
     });
 
     if (!searchResult.ok) {
+      await traceSession?.finish("failed");
       return { success: false, error: searchResult.error.message };
     }
 
@@ -261,6 +332,7 @@ export async function ask(
       answerRequested && answerPort !== null && results.length > 0;
 
     if (shouldGenerateAnswer && answerPort) {
+      await traceSession?.recordCapability("answer_generation", "attempted");
       const maxTokens = options.maxAnswerTokens ?? 512;
       const rawResult = await generateGroundedAnswer(
         { genPort: answerPort, store },
@@ -271,15 +343,25 @@ export async function ask(
 
       // Fail loudly if generation was requested but failed
       if (!rawResult) {
+        await traceSession?.recordCapability(
+          "answer_generation",
+          "failed",
+          "generation_failed"
+        );
+        await traceSession?.finish("failed");
         return {
           success: false,
           error:
             "Answer generation failed. The generation model may have encountered an error.",
         };
       }
+      await traceSession?.recordCapability("answer_generation", "used");
 
       // Process answer: extract valid citations, filter, renumber
-      const processed = processAnswerResult(rawResult);
+      const processed = await processAnswerResultWithTrace(
+        rawResult,
+        traceSession
+      );
       answer = processed.answer;
       citations = processed.citations;
       answerContext = processed.answerContext;
@@ -307,7 +389,32 @@ export async function ask(
       },
     };
 
-    return { success: true, data: askResult };
+    if (answerRequested) {
+      if (!answerGenerated) {
+        await traceSession?.recordCapability(
+          "answer_generation",
+          "unavailable",
+          "no_evidence"
+        );
+      }
+      const finalized = await traceSession?.finish(
+        answerTraceTerminalStatus(citations)
+      );
+      if (finalized && !finalized.ok) {
+        return { success: false, error: finalized.error.message };
+      }
+    }
+    return {
+      success: true,
+      data: askResult,
+      metadata: traceSession?.metadata(),
+    };
+  } catch (cause) {
+    await finishRetrievalTraceAfterError(traceSession, cause);
+    return {
+      success: false,
+      error: cause instanceof Error ? cause.message : "Ask failed",
+    };
   } finally {
     if (embedPort) {
       await embedPort.dispose();
@@ -324,149 +431,3 @@ export async function ask(
     await store.close();
   }
 }
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Formatters
-// ─────────────────────────────────────────────────────────────────────────────
-
-interface FormatOptions {
-  showSources?: boolean;
-}
-
-// oxlint-disable-next-line max-lines-per-function -- terminal formatting with conditional sections
-function formatTerminal(data: AskResult, opts: FormatOptions = {}): string {
-  const lines: string[] = [];
-  const hasAnswer = Boolean(data.answer);
-
-  // Show answer if present
-  if (data.answer) {
-    lines.push("Answer:");
-    lines.push(data.answer);
-    lines.push("");
-  }
-
-  // Show cited sources (only sources actually referenced in answer)
-  if (data.citations && data.citations.length > 0) {
-    lines.push("Cited Sources:");
-    for (let i = 0; i < data.citations.length; i++) {
-      const c = data.citations[i];
-      if (c) {
-        lines.push(`  [${i + 1}] ${c.uri}`);
-      }
-    }
-    lines.push("");
-  }
-
-  // Show all retrieved sources if:
-  // - No answer was generated (retrieval-only mode)
-  // - User explicitly requested with --show-sources
-  const showAllSources = !hasAnswer || opts.showSources;
-  if (showAllSources && data.results.length > 0) {
-    lines.push(hasAnswer ? "All Retrieved Sources:" : "Sources:");
-    for (const r of data.results) {
-      lines.push(`  [${r.docid}] ${r.uri}`);
-      if (r.title) {
-        lines.push(`    ${r.title}`);
-      }
-    }
-  } else if (hasAnswer && data.results.length > 0) {
-    // Hint about --show-sources when we have more sources
-    const citedCount = data.citations?.length ?? 0;
-    if (data.results.length > citedCount) {
-      lines.push(
-        `(${data.results.length} sources retrieved, use --show-sources to list all)`
-      );
-    }
-  }
-
-  if (!data.answer && data.results.length === 0) {
-    lines.push("No relevant sources found.");
-  }
-
-  return lines.join("\n");
-}
-
-function formatMarkdown(data: AskResult, opts: FormatOptions = {}): string {
-  const lines: string[] = [];
-  const hasAnswer = Boolean(data.answer);
-
-  lines.push(`# Question: ${data.query}`);
-  lines.push("");
-
-  if (data.answer) {
-    lines.push("## Answer");
-    lines.push("");
-    lines.push(data.answer);
-    lines.push("");
-  }
-
-  // Show cited sources (only sources actually referenced in answer)
-  if (data.citations && data.citations.length > 0) {
-    lines.push("## Cited Sources");
-    lines.push("");
-    for (let i = 0; i < data.citations.length; i++) {
-      const c = data.citations[i];
-      if (c) {
-        lines.push(`**[${i + 1}]** \`${c.uri}\``);
-      }
-    }
-    lines.push("");
-  }
-
-  // Show all retrieved sources if no answer or --show-sources
-  const showAllSources = !hasAnswer || opts.showSources;
-  if (showAllSources) {
-    lines.push(hasAnswer ? "## All Retrieved Sources" : "## Sources");
-    lines.push("");
-
-    for (let i = 0; i < data.results.length; i++) {
-      const r = data.results[i];
-      if (!r) {
-        continue;
-      }
-      lines.push(`${i + 1}. **${r.title || r.source.relPath}**`);
-      lines.push(`   - URI: \`${r.uri}\``);
-      lines.push(`   - Score: ${r.score.toFixed(2)}`);
-    }
-
-    if (data.results.length === 0) {
-      lines.push("*No relevant sources found.*");
-    }
-  }
-
-  lines.push("");
-  lines.push("---");
-  lines.push(
-    `*Mode: ${data.mode} | Expanded: ${data.meta.expanded} | Reranked: ${data.meta.reranked}*`
-  );
-
-  return lines.join("\n");
-}
-
-/**
- * Format ask result for output.
- */
-export function formatAsk(
-  result: AskCommandResult,
-  options: AskCommandOptions
-): string {
-  if (!result.success) {
-    return options.json
-      ? JSON.stringify({
-          error: { code: "ASK_FAILED", message: result.error },
-        })
-      : `Error: ${result.error}`;
-  }
-
-  const formatOpts: FormatOptions = { showSources: options.showSources };
-
-  if (options.json) {
-    return JSON.stringify(result.data, null, 2);
-  }
-
-  if (options.md) {
-    return formatMarkdown(result.data, formatOpts);
-  }
-
-  return formatTerminal(result.data, formatOpts);
-}

package/src/cli/commands/context-build.ts

@@ -1,6 +1,7 @@
 /** Context Capsule build command over the shared application runtime. */
 
 import type { ContextCapsuleBuildInput } from "../../app/context-runtime";
+import type { RetrievalTraceSession } from "../../core/retrieval-trace-session";
 import type { EmbeddingPort, RerankPort } from "../../llm/types";
 import type { VectorIndexPort } from "../../store/vector";
 
@@ -10,6 +11,10 @@ import {
   canonicalBuiltContextCapsuleJson,
   validateContextCapsuleBuildInput,
 } from "../../app/context-runtime";
+import {
+  finishRetrievalTraceAfterError,
+  startRetrievalTraceRequest,
+} from "../../core/retrieval-trace-request";
 import { LlmAdapter } from "../../llm/nodeLlamaCpp/adapter";
 import { resolveDownloadPolicy } from "../../llm/policy";
 import { resolveModelUri } from "../../llm/registry";
@@ -77,13 +82,56 @@ export const contextBuild = async (
   let embedPort: EmbeddingPort | null = null;
   let rerankPort: RerankPort | null = null;
   let vectorIndex: VectorIndexPort | null = null;
+  let traceSession: RetrievalTraceSession | undefined;
   try {
     validateContextCapsuleBuildInput(
       { goal, ...options },
       options.indexName,
       config.collections.map((collection) => collection.name)
     );
+    const collection =
+      options.collections?.length === 1 ? options.collections[0] : undefined;
+    const embedUri =
+      options.depthPolicy === "fast"
+        ? undefined
+        : resolveModelUri(config, "embed", undefined, collection);
+    const rerankUri =
+      options.depthPolicy === "fast"
+        ? undefined
+        : resolveModelUri(config, "rerank", undefined, collection);
+    const traceStart = await startRetrievalTraceRequest({
+      store,
+      config,
+      query: options.query ?? goal,
+      goal,
+      filters: {
+        limit: options.limit,
+        collection,
+        collections: [...(options.collections ?? [])].sort(),
+        lang: options.lang,
+        tagsAll: options.tagsAll,
+        tagsAny: options.tagsAny,
+        since: options.since,
+        until: options.until,
+        categories: options.categories,
+        author: options.author,
+        graph: options.graph,
+        candidateLimit: options.candidateLimit,
+        queryModes: options.queryModes,
+        uriPrefix: options.uriPrefix ?? undefined,
+      },
+      pipeline: "context",
+      indexName: options.indexName,
+      modelUris: [embedUri, rerankUri].filter((value): value is string =>
+        Boolean(value)
+      ),
+    });
+    if (!traceStart.ok) throw new Error(traceStart.error.message);
+    traceSession = traceStart.value ?? undefined;
     if (options.depthPolicy !== "fast") {
+      if (!(embedUri && rerankUri)) {
+        throw new Error("Context model identities could not be resolved");
+      }
       const globals = getGlobals();
       const policy = resolveDownloadPolicy(process.env, {
         offline: globals.offline,
@@ -92,9 +140,6 @@ export const contextBuild = async (
       const progress = showProgress
         ? createThrottledProgressRenderer(createProgressRenderer())
         : undefined;
-      const collection =
-        options.collections?.length === 1 ? options.collections[0] : undefined;
-      const embedUri = resolveModelUri(config, "embed", undefined, collection);
       const embedResult = await llm.createEmbeddingPort(embedUri, {
         policy,
         onProgress: progress ? (value) => progress("embed", value) : undefined,
@@ -110,12 +155,6 @@ export const contextBuild = async (
           if (vectorResult.ok) vectorIndex = vectorResult.value;
         }
       }
-      const rerankUri = resolveModelUri(
-        config,
-        "rerank",
-        undefined,
-        collection
-      );
       const rerankResult = await llm.createRerankPort(rerankUri, {
         policy,
         onProgress: progress ? (value) => progress("rerank", value) : undefined,
@@ -132,12 +171,20 @@ export const contextBuild = async (
         vectorIndex,
         embedPort,
         rerankPort,
+        traceSession,
       }
     );
+    const finished = await traceSession?.finish("completed");
+    if (finished && !finished.ok) throw new Error(finished.error.message);
+    const traceMetadata = traceSession?.metadata();
+    if (traceMetadata) {
+      process.stderr.write(`Trace: ${traceMetadata.traceId}\n`);
+    }
     return options.format === "md"
       ? formatContextCapsuleMarkdown(capsule)
       : canonicalBuiltContextCapsuleJson(capsule);
   } catch (error) {
+    await finishRetrievalTraceAfterError(traceSession, error);
     if (error instanceof CliError) throw error;
     throw contextCliError(error);
   } finally {

package/src/cli/commands/get.ts

@@ -5,6 +5,10 @@
  * @module src/cli/commands/get
  */
 
+import type {
+  RetrievalTraceSession,
+  RetrievalTraceSurfaceMetadata,
+} from "../../core/retrieval-trace-session";
 import type { DocumentRow, StorePort, StoreResult } from "../../store/types";
 import type { ParsedRef } from "./ref-parser";
 
@@ -17,6 +21,10 @@ import {
   getDocumentCapabilities,
   type DocumentCapabilities,
 } from "../../core/document-capabilities";
+import {
+  evidenceFromExactDocument,
+  RetrievalTraceSession as TraceSession,
+} from "../../core/retrieval-trace-session";
 import { parseRef } from "./ref-parser";
 import { initStore } from "./shared";
 
@@ -41,10 +49,18 @@ export interface GetCommandOptions {
   json?: boolean;
   /** Markdown output */
   md?: boolean;
+  /** Continue an open retrieval receipt returned by a prior query. */
+  traceId?: string;
+  /** Internal shared-session seam for in-process callers. */
+  traceSession?: RetrievalTraceSession;
 }
 
 export type GetResult =
-  | { success: true; data: GetResponse }
+  | {
+      success: true;
+      data: GetResponse;
+      metadata?: RetrievalTraceSurfaceMetadata;
+    }
   | { success: false; error: string; isValidation?: boolean };
 
 export interface GetResponse {
@@ -138,7 +154,53 @@ export async function get(
   const { store, config } = initResult;
 
   try {
-    return await fetchDocument(store, parsed, options, config, indexName);
+    let traceSession = options.traceSession;
+    if (!traceSession && options.traceId) {
+      const resumed = await TraceSession.resume({
+        store,
+        config: config.retrievalTraces,
+        traceId: options.traceId,
+      });
+      if (!resumed.ok) {
+        return { success: false, error: resumed.error.message };
+      }
+      traceSession = resumed.value ?? undefined;
+    }
+    const result = await fetchDocument(
+      store,
+      parsed,
+      options,
+      config,
+      indexName
+    );
+    if (!result.success || !traceSession) return result;
+    const lines = result.data.returnedLines ?? {
+      start: 1,
+      end: result.data.totalLines,
+    };
+    const evidence = evidenceFromExactDocument({
+      docid: result.data.docid,
+      uri: result.data.uri,
+      sourceHash: result.data.source.sourceHash,
+      mirrorHash: result.data.conversion?.mirrorHash,
+      content: result.data.content,
+      startLine: lines.start,
+      endLine: lines.end,
+    });
+    if (evidence) {
+      const getEvent = await traceSession.recordEvidence("get", [evidence]);
+      if (!getEvent.ok) {
+        return { success: false, error: getEvent.error.message };
+      }
+      const openEvent = await traceSession.recordEvidence("open", [evidence]);
+      if (!openEvent.ok) {
+        return { success: false, error: openEvent.error.message };
+      }
+    }
+    return {
+      ...result,
+      metadata: traceSession.metadata(),
+    };
   } finally {
     await store.close();
   }
@@ -375,7 +437,6 @@ export function formatGet(
     }
     return `Error: ${result.error}`;
   }
-
   const { data } = result;
 
   if (options.json) {