@gmickel/gno 1.18.0 → 1.19.0

package/src/cli/commands/vsearch.ts

@@ -5,8 +5,18 @@
  * @module src/cli/commands/vsearch
  */
 
+import type {
+  RetrievalTraceSession,
+  RetrievalTraceSurfaceMetadata,
+} from "../../core/retrieval-trace-session";
+import type { EmbeddingPort } from "../../llm/types";
 import type { SearchOptions, SearchResults } from "../../pipeline/types";
 
+import {
+  finishRetrievalTraceAfterError,
+  retrievalTraceFilters,
+  startRetrievalTraceRequest,
+} from "../../core/retrieval-trace-request";
 import { LlmAdapter } from "../../llm/nodeLlamaCpp/adapter";
 import { resolveModelUri } from "../../llm/registry";
 import { formatQueryForEmbedding } from "../../pipeline/contextual";
@@ -47,7 +57,11 @@ export type VsearchCommandOptions = SearchOptions & {
 };
 
 export type VsearchResult =
-  | { success: true; data: SearchResults }
+  | {
+      success: true;
+      data: SearchResults;
+      metadata?: RetrievalTraceSurfaceMetadata;
+    }
   | { success: false; error: string };
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -78,6 +92,8 @@ export async function vsearch(
   }
 
   const { store, config } = initResult;
+  let embedPort: EmbeddingPort | null = null;
+  let traceSession: RetrievalTraceSession | undefined;
 
   try {
     // Get model URI from preset
@@ -87,67 +103,74 @@ export async function vsearch(
       options.model,
       options.collection
     );
+    const traceStart = await startRetrievalTraceRequest({
+      store,
+      config,
+      query,
+      filters: retrievalTraceFilters({ ...options, limit }),
+      pipeline: "vector",
+      indexName: options.indexName,
+      modelUris: [modelUri],
+    });
+    if (!traceStart.ok) {
+      return { success: false, error: traceStart.error.message };
+    }
+    traceSession = traceStart.value ?? undefined;
 
     // Create LLM adapter for embeddings
     const llm = new LlmAdapter(config);
     const embedResult = await llm.createEmbeddingPort(modelUri);
     if (!embedResult.ok) {
+      await traceSession?.finish("failed");
       return { success: false, error: embedResult.error.message };
     }
 
-    const embedPort = embedResult.value;
-
-    try {
-      // Embed query with contextual formatting (also determines dimensions)
-      const queryEmbedResult = await embedPort.embed(
-        formatQueryForEmbedding(query, embedPort.modelUri)
-      );
-      if (!queryEmbedResult.ok) {
-        return { success: false, error: queryEmbedResult.error.message };
-      }
-      const queryEmbedding = new Float32Array(queryEmbedResult.value);
-      const dimensions = queryEmbedding.length;
-
-      // Create vector index port
-      const db = store.getRawDb();
-      const vectorResult = await createVectorIndexPort(db, {
-        model: modelUri,
-        dimensions,
-      });
-
-      if (!vectorResult.ok) {
-        return { success: false, error: vectorResult.error.message };
-      }
-
-      const vectorIndex = vectorResult.value;
-
-      const deps: VectorSearchDeps = {
-        store,
-        vectorIndex,
-        embedPort,
-        config,
-      };
-
-      // Pass pre-computed embedding to avoid double-embed
-      const result = await searchVectorWithEmbedding(
-        deps,
-        query,
-        queryEmbedding,
-        { ...options, limit }
-      );
-
-      if (!result.ok) {
-        return { success: false, error: result.error.message };
-      }
-
-      return {
-        success: true,
-        data: decorateSearchResultsForIndex(result.value, options.indexName),
-      };
-    } finally {
-      await embedPort.dispose();
+    embedPort = embedResult.value;
+    const queryEmbedResult = await embedPort.embed(
+      formatQueryForEmbedding(query, embedPort.modelUri)
+    );
+    if (!queryEmbedResult.ok) {
+      await traceSession?.finish("failed");
+      return { success: false, error: queryEmbedResult.error.message };
     }
+    const queryEmbedding = new Float32Array(queryEmbedResult.value);
+    const vectorResult = await createVectorIndexPort(store.getRawDb(), {
+      model: modelUri,
+      dimensions: queryEmbedding.length,
+    });
+    if (!vectorResult.ok) {
+      await traceSession?.finish("failed");
+      return { success: false, error: vectorResult.error.message };
+    }
+    const deps: VectorSearchDeps = {
+      store,
+      vectorIndex: vectorResult.value,
+      embedPort,
+      config,
+    };
+    const result = await searchVectorWithEmbedding(
+      deps,
+      query,
+      queryEmbedding,
+      { ...options, limit, traceSession }
+    );
+    if (!result.ok) {
+      await traceSession?.finish("failed");
+      return { success: false, error: result.error.message };
+    }
+    return {
+      success: true,
+      data: decorateSearchResultsForIndex(result.value, options.indexName),
+      metadata: traceSession?.metadata(),
+    };
+  } catch (cause) {
+    await finishRetrievalTraceAfterError(traceSession, cause);
+    return {
+      success: false,
+      error: cause instanceof Error ? cause.message : "Vector search failed",
+    };
   } finally {
+    await embedPort?.dispose();
     await store.close();
   }
 }
@@ -194,7 +217,6 @@ export function formatVsearch(
         })
       : `Error: ${result.error}`;
   }
-
   const formatOpts: FormatOptions = {
     format: getFormatType(options),
     full: options.full,

package/src/cli/program.ts

@@ -164,6 +164,15 @@ async function writeOutput(
   }
 }
 
+/** Emit opt-in trace identity without changing command stdout payloads. */
+export function writeRetrievalTraceReceipt(
+  metadata: { traceId: string } | undefined
+): void {
+  if (metadata) {
+    process.stderr.write(`Trace: ${metadata.traceId}\n`);
+  }
+}
+
 async function resolveTerminalLinkPolicy(
   format: "terminal" | "json" | "files" | "csv" | "md" | "xml"
 ): Promise<
@@ -292,6 +301,7 @@ export function createProgram(): Command {
   wireOnboardingCommands(program);
   wireCaptureCommand(program);
   wireManagementCommands(program);
+  wireTraceCommands(program);
   wirePublishCommand(program);
   wireVecCommands(program);
   wireRetrievalCommands(program);
@@ -315,6 +325,244 @@ Report issues: ${ISSUES_URL}`
   return program;
 }
 
+function wireTraceCommands(program: Command): void {
+  const traceCmd = program
+    .command("trace")
+    .description("Inspect and manage private local retrieval traces");
+
+  const outputFormat = (options: Record<string, unknown>): "json" | "md" =>
+    getFormat(options) === "json" ? "json" : "md";
+
+  traceCmd
+    .command("list")
+    .description("List bounded, redacted retrieval trace summaries")
+    .option("-n, --limit <num>", "maximum traces", "50")
+    .option("--cursor <cursor>", "continue from a previous list receipt")
+    .option("--json", "JSON output")
+    .option("--md", "Markdown output")
+    .action(async (cmdOpts: Record<string, unknown>) => {
+      const globals = getGlobals();
+      const { traceList } = await import("./commands/trace");
+      const output = await traceList(
+        {
+          limit: parsePositiveInt("limit", cmdOpts.limit),
+          cursor: cmdOpts.cursor as string | undefined,
+        },
+        {
+          configPath: globals.config,
+          indexName: globals.index,
+          format: outputFormat(cmdOpts),
+        }
+      );
+      process.stdout.write(output);
+    });
+
+  traceCmd
+    .command("show <trace-id>")
+    .description("Inspect one bounded retrieval trace receipt")
+    .option("--detail-limit <num>", "maximum records per detail section", "500")
+    .option("--json", "JSON output")
+    .option("--md", "Markdown output")
+    .action(async (traceId: string, cmdOpts: Record<string, unknown>) => {
+      const globals = getGlobals();
+      const { traceShow } = await import("./commands/trace");
+      const output = await traceShow(
+        traceId,
+        {
+          detailLimit: parsePositiveInt("detail-limit", cmdOpts.detailLimit),
+        },
+        {
+          configPath: globals.config,
+          indexName: globals.index,
+          format: outputFormat(cmdOpts),
+        }
+      );
+      process.stdout.write(output);
+    });
+
+  traceCmd
+    .command("label <trace-id>")
+    .description("Append an explicit retrieval relevance judgment")
+    .requiredOption(
+      "--label <label>",
+      "relevant, irrelevant, or missing-expected"
+    )
+    .requiredOption("--target <ref>", "evidence or expected-document reference")
+    .option("--target-kind <kind>", "document, chunk, or span")
+    .option("--from-line <num>", "exact evidence start line")
+    .option("--to-line <num>", "exact evidence end line")
+    .option("--source-hash <sha256>", "expected immutable source hash")
+    .option("--docid <docid>", "expected document ID")
+    .option("--idempotency-key <key>", "caller retry key")
+    .option("--json", "JSON output")
+    .option("--md", "Markdown output")
+    .action(async (traceId: string, cmdOpts: Record<string, unknown>) => {
+      const globals = getGlobals();
+      const rawLabel = String(cmdOpts.label).replace("-", "_");
+      if (!["relevant", "irrelevant", "missing_expected"].includes(rawLabel)) {
+        throw new CliError(
+          "VALIDATION",
+          "--label must be relevant, irrelevant, or missing-expected"
+        );
+      }
+      const rawTargetKind = cmdOpts.targetKind;
+      if (
+        rawTargetKind !== undefined &&
+        (typeof rawTargetKind !== "string" ||
+          !["document", "chunk", "span"].includes(rawTargetKind))
+      ) {
+        throw new CliError(
+          "VALIDATION",
+          "--target-kind must be document, chunk, or span"
+        );
+      }
+      const { traceLabel } = await import("./commands/trace");
+      const output = await traceLabel(
+        {
+          traceId,
+          label: rawLabel as "relevant" | "irrelevant" | "missing_expected",
+          targetRef: String(cmdOpts.target),
+          targetKind: rawTargetKind as
+            | "document"
+            | "chunk"
+            | "span"
+            | undefined,
+          startLine:
+            cmdOpts.fromLine === undefined
+              ? undefined
+              : parsePositiveInt("from-line", cmdOpts.fromLine),
+          endLine:
+            cmdOpts.toLine === undefined
+              ? undefined
+              : parsePositiveInt("to-line", cmdOpts.toLine),
+          sourceHash: cmdOpts.sourceHash as string | undefined,
+          docid: cmdOpts.docid as string | undefined,
+          idempotencyKey: cmdOpts.idempotencyKey as string | undefined,
+        },
+        {
+          configPath: globals.config,
+          indexName: globals.index,
+          format: outputFormat(cmdOpts),
+        }
+      );
+      process.stdout.write(output);
+    });
+
+  traceCmd
+    .command("export <trace-ids...>")
+    .description("Export immutable terminal traces as one local receipt")
+    .option("--format <format>", "agentic-receipt or qrels", "agentic-receipt")
+    .option("--output <path>", "write canonical artifact atomically")
+    .option("--json", "JSON output")
+    .action(async (traceIds: string[], cmdOpts: Record<string, unknown>) => {
+      const globals = getGlobals();
+      const exportFormat = String(cmdOpts.format);
+      if (!["agentic-receipt", "qrels"].includes(exportFormat)) {
+        throw new CliError(
+          "VALIDATION",
+          "--format must be agentic-receipt or qrels"
+        );
+      }
+      const { traceExport } = await import("./commands/trace");
+      process.stdout.write(
+        await traceExport(traceIds, {
+          configPath: globals.config,
+          indexName: globals.index,
+          format: "json",
+          output: cmdOpts.output as string | undefined,
+          exportFormat: exportFormat as "agentic-receipt" | "qrels",
+        })
+      );
+    });
+
+  traceCmd
+    .command("replay <export-id>")
+    .description("Compare one immutable qrels baseline with a candidate")
+    .requiredOption("--candidate <type>", "bm25, vector, or hybrid")
+    .option("-n, --limit <num>", "result cutoff")
+    .option("--candidate-limit <num>", "candidate pool size")
+    .option("--no-expand", "disable query expansion")
+    .option("--no-rerank", "disable reranking")
+    .option("--json", "JSON output")
+    .option("--md", "Markdown output")
+    .action(async (exportId: string, cmdOpts: Record<string, unknown>) => {
+      const globals = getGlobals();
+      const candidateType = String(cmdOpts.candidate);
+      if (!["bm25", "vector", "hybrid"].includes(candidateType)) {
+        throw new CliError(
+          "VALIDATION",
+          "--candidate must be bm25, vector, or hybrid"
+        );
+      }
+      const { traceReplay } = await import("./commands/replay");
+      process.stdout.write(
+        await traceReplay(
+          exportId,
+          {
+            id: `cli-${candidateType}`,
+            type: candidateType as "bm25" | "vector" | "hybrid",
+            limit:
+              cmdOpts.limit === undefined
+                ? undefined
+                : parsePositiveInt("limit", cmdOpts.limit),
+            candidateLimit:
+              cmdOpts.candidateLimit === undefined
+                ? undefined
+                : parsePositiveInt("candidate-limit", cmdOpts.candidateLimit),
+            noExpand: cmdOpts.expand === false,
+            noRerank: cmdOpts.rerank === false,
+          },
+          {
+            configPath: globals.config,
+            indexName: globals.index,
+            format: outputFormat(cmdOpts),
+            offline: globals.offline,
+          }
+        )
+      );
+    });
+
+  traceCmd
+    .command("delete <trace-id>")
+    .description("Delete one trace and every owned local record")
+    .option("--json", "JSON output")
+    .option("--md", "Markdown output")
+    .action(async (traceId: string, cmdOpts: Record<string, unknown>) => {
+      const globals = getGlobals();
+      const { traceDelete } = await import("./commands/trace");
+      process.stdout.write(
+        await traceDelete(traceId, {
+          configPath: globals.config,
+          indexName: globals.index,
+          format: outputFormat(cmdOpts),
+        })
+      );
+    });
+
+  traceCmd
+    .command("purge")
+    .description("Delete every local retrieval trace receipt")
+    .option("--json", "JSON output")
+    .option("--md", "Markdown output")
+    .action(async (cmdOpts: Record<string, unknown>) => {
+      const globals = getGlobals();
+      if (!globals.yes) {
+        throw new CliError(
+          "VALIDATION",
+          "Trace purge requires the global --yes confirmation"
+        );
+      }
+      const { tracePurge } = await import("./commands/trace");
+      process.stdout.write(
+        await tracePurge({
+          configPath: globals.config,
+          indexName: globals.index,
+          format: outputFormat(cmdOpts),
+        })
+      );
+    });
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Search Commands (search, vsearch, query, ask)
 // ─────────────────────────────────────────────────────────────────────────────
@@ -435,6 +683,7 @@ function wireSearchCommands(program: Command): void {
         terminalLinks: await resolveTerminalLinkPolicy(format),
       });
       await writeOutput(output, format);
+      writeRetrievalTraceReceipt(result.metadata);
     });
 
   // vsearch - Vector similarity search
@@ -547,6 +796,7 @@ function wireSearchCommands(program: Command): void {
         terminalLinks: await resolveTerminalLinkPolicy(format),
       });
       await writeOutput(output, format);
+      writeRetrievalTraceReceipt(result.metadata);
     });
 
   // query - Hybrid search with expansion and reranking
@@ -768,6 +1018,7 @@ function wireSearchCommands(program: Command): void {
         terminalLinks: await resolveTerminalLinkPolicy(format),
       });
       await writeOutput(output, format);
+      writeRetrievalTraceReceipt(result.metadata);
     });
 
   // bench - Retrieval benchmark fixture runner
@@ -960,6 +1211,7 @@ function wireSearchCommands(program: Command): void {
         showSources,
       });
       await writeOutput(output, format);
+      writeRetrievalTraceReceipt(result.metadata);
     });
 }
 
@@ -1191,6 +1443,7 @@ function wireRetrievalCommands(program: Command): void {
       parsePositiveInt.bind(null, "limit")
     )
     .option("--line-numbers", "Prefix lines with numbers")
+    .option("--trace-id <id>", "Continue an open retrieval trace")
     .option("--source", "Include source metadata")
     .option("--json", "JSON output")
     .option("--md", "Markdown output")
@@ -1209,6 +1462,7 @@ function wireRetrievalCommands(program: Command): void {
         source: Boolean(cmdOpts.source),
         json: format === "json",
         md: format === "md",
+        traceId: cmdOpts.traceId as string | undefined,
       });
 
       if (!result.success) {
@@ -1225,6 +1479,7 @@ function wireRetrievalCommands(program: Command): void {
           md: format === "md",
         })}\n`
       );
+      writeRetrievalTraceReceipt(result.metadata);
     });
 
   // multi-get - Retrieve multiple documents

package/src/config/index.ts

@@ -70,3 +70,12 @@ export {
   ScopeTypeSchema,
 } from "./types";
 export type { HttpGatewayConfig } from "./types";
+export {
+  RETRIEVAL_TRACE_DEFAULT_RETENTION,
+  type RetrievalTraceConfig,
+  RetrievalTraceConfigSchema,
+  type RetrievalTraceRedactionMode,
+  RetrievalTraceRedactionModeSchema,
+  type RetrievalTraceRetention,
+  RetrievalTraceRetentionSchema,
+} from "./retrieval-traces";

package/src/config/retrieval-traces.ts

@@ -0,0 +1,56 @@
+/** Opt-in retrieval trace configuration and bounded-retention defaults. */
+
+import { z } from "zod";
+
+export const RETRIEVAL_TRACE_DEFAULT_RETENTION = {
+  maxAgeDays: 30,
+  maxTraces: 1_000,
+  maxRecordsPerTrace: 10_000,
+  maxBytes: 16 * 1024 * 1024,
+} as const;
+
+export const RetrievalTraceRetentionSchema = z
+  .object({
+    maxAgeDays: z.number().int().min(1).max(3_650),
+    maxTraces: z.number().int().min(1).max(1_000_000),
+    maxRecordsPerTrace: z.number().int().min(1).max(100_000),
+    maxBytes: z
+      .number()
+      .int()
+      .min(64 * 1024)
+      .max(1024 * 1024 * 1024),
+  })
+  .strict();
+
+export const RetrievalTraceRedactionModeSchema = z.enum(["metadata", "replay"]);
+
+const DisabledRetrievalTraceConfigSchema = z
+  .object({
+    enabled: z.literal(false),
+  })
+  .strict();
+
+const EnabledRetrievalTraceConfigSchema = z
+  .object({
+    enabled: z.literal(true),
+    /**
+     * `replay` stores replay inputs such as the raw query and filters. Choosing
+     * it is explicit consent; the safer metadata-only projection is recommended.
+     */
+    redactionMode: RetrievalTraceRedactionModeSchema,
+    retention: RetrievalTraceRetentionSchema,
+  })
+  .strict();
+
+export const RetrievalTraceConfigSchema = z.discriminatedUnion("enabled", [
+  DisabledRetrievalTraceConfigSchema,
+  EnabledRetrievalTraceConfigSchema,
+]);
+
+export type RetrievalTraceConfig = z.infer<typeof RetrievalTraceConfigSchema>;
+export type RetrievalTraceRetention = z.infer<
+  typeof RetrievalTraceRetentionSchema
+>;
+export type RetrievalTraceRedactionMode = z.infer<
+  typeof RetrievalTraceRedactionModeSchema
+>;

package/src/config/types.ts

@@ -8,6 +8,7 @@
 import { z } from "zod";
 
 import { URI_PREFIX } from "../app/constants";
+import { RetrievalTraceConfigSchema } from "./retrieval-traces";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Constants
@@ -338,6 +339,9 @@ export const ConfigSchema = z.object({
 
   /** Resident Streamable HTTP MCP gateway configuration */
   gateway: HttpGatewayConfigSchema.optional(),
+
+  /** Private local retrieval trace recording. Absent means recording off. */
+  retrievalTraces: RetrievalTraceConfigSchema.optional(),
 });
 
 export type Config = Omit<z.infer<typeof ConfigSchema>, "contentTypes"> & {

package/src/core/context-compiler.ts

@@ -29,6 +29,7 @@ import type { ContextConfiguredGuidance } from "./context-guidance";
 import { decorateUriForIndex } from "../app/constants";
 import { canonicalizeIndexName } from "../app/index-name";
 import { resolveTemporalRange } from "../pipeline/temporal";
+import { attachSearchResultPlannerMetadata } from "../pipeline/trace-metadata";
 import {
   SEARCH_RESULT_PLANNER_METADATA,
   type SearchResultPlannerMetadata,
@@ -363,10 +364,16 @@ export const planContextEvidence = async <T, P>(
   }
   const decoratedResults = responses
     .flatMap((response) => response.results)
-    .map((result) => ({
-      ...result,
-      uri: decorateUriForIndex(result.uri, indexName),
-    }));
+    .map((result) => {
+      const decorated = {
+        ...result,
+        uri: decorateUriForIndex(result.uri, indexName),
+      };
+      const metadata = result[SEARCH_RESULT_PLANNER_METADATA];
+      return metadata
+        ? attachSearchResultPlannerMetadata(decorated, metadata)
+        : decorated;
+    });
   const results = decoratedResults
     .map((result, index) => ({
       result,