@gmickel/gno 1.18.0 → 1.20.0

package/src/serve/routes/api.ts

@@ -36,6 +36,7 @@ import type { StartJobError } from "../jobs";
 import type { ResidentStatus } from "../status-model";
 import type { CollectionWatchService } from "../watch-service";
 
+import { buildVerifiedAsk } from "../../app/verified-ask";
 import { modelsPull } from "../../cli/commands/models/pull";
 import {
   addCollection,
@@ -94,6 +95,14 @@ import {
   resolveNotePreset,
   type NotePresetId,
 } from "../../core/note-presets";
+import {
+  retrievalTraceFilters,
+  startRetrievalTraceRequest,
+} from "../../core/retrieval-trace-request";
+import {
+  evidenceFromExactDocument,
+  RetrievalTraceSession,
+} from "../../core/retrieval-trace-session";
 import { extractSections } from "../../core/sections";
 import { normalizeStructuredQueryInput } from "../../core/structured-query";
 import {
@@ -117,8 +126,9 @@ import {
   resolveModelUri,
 } from "../../llm/registry";
 import {
+  answerTraceTerminalStatus,
   generateGroundedAnswer,
-  processAnswerResult,
+  processAnswerResultWithTrace,
 } from "../../pipeline/answer";
 import { diagnoseQueryTarget } from "../../pipeline/diagnose";
 import { searchHybrid } from "../../pipeline/hybrid";
@@ -145,6 +155,10 @@ import {
 } from "../context";
 import { analyzeImportPath } from "../import-preview";
 import { getActiveJob, getJobStatus, startJob } from "../jobs";
+import {
+  requestRetrievalTraceId,
+  withRetrievalTraceHeader,
+} from "../retrieval-trace";
 import { buildAppStatus, type StatusBuildDeps } from "../status";
 
 /** Mutable context holder for hot-reloading presets */
@@ -277,14 +291,46 @@ export interface AskRequestBody {
   category?: string;
   author?: string;
   maxAnswerTokens?: number;
+  verify?: boolean;
+  contextBudgetTokens?: number;
+  contextBudgetBytes?: number;
+  minScore?: number;
   noExpand?: boolean;
   noRerank?: boolean;
+  graph?: boolean;
+  noGraph?: boolean;
   /** Comma-separated tags - filter to docs having ALL (AND) */
   tagsAll?: string;
   /** Comma-separated tags - filter to docs having ANY (OR) */
   tagsAny?: string;
 }
 
+const ASK_REQUEST_KEYS = new Set<keyof AskRequestBody>([
+  "query",
+  "limit",
+  "collection",
+  "lang",
+  "intent",
+  "candidateLimit",
+  "exclude",
+  "queryModes",
+  "since",
+  "until",
+  "category",
+  "author",
+  "maxAnswerTokens",
+  "verify",
+  "contextBudgetTokens",
+  "contextBudgetBytes",
+  "minScore",
+  "noExpand",
+  "noRerank",
+  "graph",
+  "noGraph",
+  "tagsAll",
+  "tagsAny",
+]);
+
 export interface CreateCollectionRequestBody {
   path: string;
   name?: string;
@@ -460,6 +506,66 @@ function errorResponse(
   );
 }
 
+interface RestTraceStart {
+  session: RetrievalTraceSession | null;
+  error: Response | null;
+}
+
+async function startRestTrace(
+  ctx: ServerContext,
+  input: {
+    query: string;
+    goal?: string;
+    filters?: Record<string, unknown>;
+    pipeline: string;
+    modelUris?: string[];
+  }
+): Promise<RestTraceStart> {
+  const started = await startRetrievalTraceRequest({
+    store: ctx.store,
+    config: ctx.config,
+    query: input.query,
+    goal: input.goal,
+    filters: input.filters,
+    pipeline: input.pipeline,
+    indexName: ctx.indexName,
+    modelUris: input.modelUris,
+  });
+  return started.ok
+    ? { session: started.value, error: null }
+    : {
+        session: null,
+        error: errorResponse(
+          "RUNTIME",
+          `Retrieval trace start failed: ${started.error.message}`,
+          500
+        ),
+      };
+}
+
+async function finishRestTrace(
+  request: Request,
+  session: RetrievalTraceSession | null,
+  status: "completed" | "partial" | "failed" | "cancelled",
+  response: Response
+): Promise<Response> {
+  if (!session) return response;
+  const terminalStatus =
+    request.signal.aborted || status === "cancelled" ? "cancelled" : status;
+  const finished = await session.finish(terminalStatus);
+  if (!finished.ok) {
+    return withRetrievalTraceHeader(
+      errorResponse(
+        "RUNTIME",
+        `Retrieval trace finalization failed: ${finished.error.message}`,
+        500
+      ),
+      session
+    );
+  }
+  return withRetrievalTraceHeader(response, session);
+}
+
 function jobConflictResponse(jobResult: StartJobError): Response {
   return errorResponse("CONFLICT", jobResult.error, 409, {
     activeJobId: jobResult.activeJobId,
@@ -1639,7 +1745,8 @@ export async function handleDocsAutocomplete(
 export async function handleDoc(
   store: SqliteAdapter,
   config: Config,
-  url: URL
+  url: URL,
+  request?: Request
 ): Promise<Response> {
   const uri = url.searchParams.get("uri");
   if (!uri) {
@@ -1679,7 +1786,7 @@ export async function handleDoc(
   });
   const source = await buildSourceMeta(config.collections, doc);
 
-  return jsonResponse({
+  const responseData = {
     docid: doc.docid,
     uri: doc.uri,
     title: doc.title,
@@ -1690,7 +1797,52 @@ export async function handleDoc(
     tags,
     source,
     capabilities,
+  };
+  const continuationTraceId = request
+    ? requestRetrievalTraceId(request)
+    : undefined;
+  if (!continuationTraceId) return jsonResponse(responseData);
+
+  const resumed = await RetrievalTraceSession.resume({
+    store,
+    config: config.retrievalTraces,
+    traceId: continuationTraceId,
   });
+  if (!resumed.ok) {
+    return errorResponse("RUNTIME", resumed.error.message, 500);
+  }
+  const traceSession = resumed.value;
+  if (!traceSession) return jsonResponse(responseData);
+
+  if (content !== null) {
+    const endLine = content.split("\n").length;
+    const evidence = evidenceFromExactDocument({
+      docid: doc.docid,
+      uri: doc.uri,
+      sourceHash: doc.sourceHash,
+      mirrorHash: doc.mirrorHash ?? undefined,
+      content,
+      startLine: 1,
+      endLine,
+    });
+    if (evidence) {
+      const got = await traceSession.recordEvidence("get", [evidence]);
+      if (!got.ok) {
+        return withRetrievalTraceHeader(
+          errorResponse("RUNTIME", got.error.message, 500),
+          traceSession
+        );
+      }
+      const opened = await traceSession.recordEvidence("open", [evidence]);
+      if (!opened.ok) {
+        return withRetrievalTraceHeader(
+          errorResponse("RUNTIME", opened.error.message, 500),
+          traceSession
+        );
+      }
+    }
+  }
+  return withRetrievalTraceHeader(jsonResponse(responseData), traceSession);
 }
 
 /**
@@ -3372,9 +3524,13 @@ export async function handleCreateDoc(
  * Returns search results.
  */
 export async function handleSearch(
-  store: SqliteAdapter,
+  contextOrStore: ServerContext | SqliteAdapter,
   req: Request
 ): Promise<Response> {
+  const context =
+    "store" in contextOrStore ? contextOrStore : (null as ServerContext | null);
+  const store =
+    "store" in contextOrStore ? contextOrStore.store : contextOrStore;
   let body: SearchRequestBody;
   try {
     body = (await req.json()) as SearchRequestBody;
@@ -3382,6 +3538,9 @@ export async function handleSearch(
     return errorResponse("VALIDATION", "Invalid JSON body");
   }
 
+  if (body === null || typeof body !== "object" || Array.isArray(body)) {
+    return errorResponse("VALIDATION", "Request body must be an object");
+  }
   if (!body.query || typeof body.query !== "string") {
     return errorResponse("VALIDATION", "Missing or invalid query");
   }
@@ -3486,13 +3645,30 @@ export async function handleSearch(
     author,
   };
 
-  const result = await searchBm25(store, rawQuery, options);
+  const trace = context
+    ? await startRestTrace(context, {
+        query: rawQuery,
+        filters: retrievalTraceFilters(options),
+        pipeline: "bm25",
+      })
+    : { session: null, error: null };
+  if (trace.error) return trace.error;
+
+  const result = await searchBm25(store, rawQuery, {
+    ...options,
+    traceSession: trace.session ?? undefined,
+  });
 
   if (!result.ok) {
-    return errorResponse("RUNTIME", result.error.message, 500);
+    return finishRestTrace(
+      req,
+      trace.session,
+      "failed",
+      errorResponse("RUNTIME", result.error.message, 500)
+    );
   }
 
-  return jsonResponse(result.value);
+  return withRetrievalTraceHeader(jsonResponse(result.value), trace.session);
 }
 
 /**
@@ -3626,6 +3802,41 @@ export async function handleQuery(
     : undefined;
   const author = body.author?.trim() || undefined;
 
+  const queryOptions = {
+    limit: Math.min(body.limit ?? 20, 50),
+    minScore: body.minScore,
+    collection: body.collection,
+    lang: body.lang,
+    intent: body.intent?.trim() || undefined,
+    candidateLimit:
+      body.candidateLimit !== undefined
+        ? Math.min(body.candidateLimit, 100)
+        : undefined,
+    exclude,
+    queryModes: normalizedQueryModes,
+    noExpand: body.noExpand,
+    noRerank: body.noRerank,
+    graph: body.graph === true,
+    noGraph: body.noGraph,
+    tagsAll,
+    tagsAny,
+    since: body.since,
+    until: body.until,
+    categories,
+    author,
+  };
+  const trace = await startRestTrace(ctx, {
+    query: normalizedQuery,
+    filters: retrievalTraceFilters(queryOptions),
+    pipeline: "hybrid",
+    modelUris: [
+      ctx.embedPort?.modelUri,
+      ctx.expandPort?.modelUri,
+      ctx.rerankPort?.modelUri,
+    ].filter((value): value is string => Boolean(value)),
+  });
+  if (trace.error) return trace.error;
+
   const result = await searchHybrid(
     {
       store: ctx.store,
@@ -3637,35 +3848,21 @@ export async function handleQuery(
     },
     normalizedQuery,
     {
-      limit: Math.min(body.limit ?? 20, 50),
-      minScore: body.minScore,
-      collection: body.collection,
-      lang: body.lang,
-      intent: body.intent?.trim() || undefined,
-      candidateLimit:
-        body.candidateLimit !== undefined
-          ? Math.min(body.candidateLimit, 100)
-          : undefined,
-      exclude,
-      queryModes: normalizedQueryModes,
-      noExpand: body.noExpand,
-      noRerank: body.noRerank,
-      graph: body.graph === true,
-      noGraph: body.noGraph,
-      tagsAll,
-      tagsAny,
-      since: body.since,
-      until: body.until,
-      categories,
-      author,
+      ...queryOptions,
+      traceSession: trace.session ?? undefined,
     }
   );
 
   if (!result.ok) {
-    return errorResponse("RUNTIME", result.error.message, 500);
+    return finishRestTrace(
+      req,
+      trace.session,
+      "failed",
+      errorResponse("RUNTIME", result.error.message, 500)
+    );
   }
 
-  return jsonResponse(result.value);
+  return withRetrievalTraceHeader(jsonResponse(result.value), trace.session);
 }
 
 /**
@@ -3869,21 +4066,81 @@ export async function handleAsk(
     return errorResponse("VALIDATION", "Invalid JSON body");
   }
 
+  if (body === null || typeof body !== "object" || Array.isArray(body)) {
+    return errorResponse("VALIDATION", "Request body must be an object");
+  }
+  const unknownKey = Object.keys(body).find(
+    (key) => !ASK_REQUEST_KEYS.has(key as keyof AskRequestBody)
+  );
+  if (unknownKey) {
+    return errorResponse(
+      "VALIDATION",
+      `Unknown Ask request field: ${unknownKey}`
+    );
+  }
   if (!body.query || typeof body.query !== "string") {
     return errorResponse("VALIDATION", "Missing or invalid query");
   }
 
+  for (const field of [
+    "verify",
+    "noExpand",
+    "noRerank",
+    "graph",
+    "noGraph",
+  ] as const) {
+    if (body[field] !== undefined && typeof body[field] !== "boolean") {
+      return errorResponse("VALIDATION", `${field} must be a boolean`);
+    }
+  }
+  for (const [field, value, maximum] of [
+    ["limit", body.limit, 20],
+    ["candidateLimit", body.candidateLimit, 100],
+    ["maxAnswerTokens", body.maxAnswerTokens, Number.MAX_SAFE_INTEGER],
+  ] as const) {
+    if (
+      value !== undefined &&
+      (!Number.isSafeInteger(value) || value < 1 || value > maximum)
+    ) {
+      return errorResponse(
+        "VALIDATION",
+        `${field} must be a positive integer${maximum < Number.MAX_SAFE_INTEGER ? ` no greater than ${maximum}` : ""}`
+      );
+    }
+  }
+
   const rawQuery = body.query.trim();
   if (!rawQuery) {
     return errorResponse("VALIDATION", "Query cannot be empty");
   }
 
-  // Check if answer generation is available
-  if (!ctx.capabilities.answer) {
+  if (
+    body.minScore !== undefined &&
+    (typeof body.minScore !== "number" ||
+      !Number.isFinite(body.minScore) ||
+      body.minScore < 0 ||
+      body.minScore > 1)
+  ) {
+    return errorResponse("VALIDATION", "minScore must be between 0 and 1");
+  }
+  if (
+    body.contextBudgetTokens !== undefined &&
+    (!Number.isSafeInteger(body.contextBudgetTokens) ||
+      body.contextBudgetTokens < 1)
+  ) {
     return errorResponse(
-      "UNAVAILABLE",
-      "Answer generation not available. No answer model loaded.",
-      503
+      "VALIDATION",
+      "contextBudgetTokens must be a positive integer"
+    );
+  }
+  if (
+    body.contextBudgetBytes !== undefined &&
+    (!Number.isSafeInteger(body.contextBudgetBytes) ||
+      body.contextBudgetBytes < 1)
+  ) {
+    return errorResponse(
+      "VALIDATION",
+      "contextBudgetBytes must be a positive integer"
     );
   }
 
@@ -3973,6 +4230,103 @@ export async function handleAsk(
   const author = body.author?.trim() || undefined;
 
   const limit = Math.min(body.limit ?? 5, 20);
+  const askOptions = {
+    limit,
+    collection: body.collection,
+    lang: body.lang,
+    intent: body.intent?.trim() || undefined,
+    minScore: body.minScore,
+    noExpand: body.noExpand,
+    noRerank: body.noRerank,
+    candidateLimit:
+      body.candidateLimit !== undefined
+        ? Math.min(body.candidateLimit, 100)
+        : undefined,
+    exclude,
+    graph: body.graph,
+    noGraph: body.noGraph,
+    queryModes: normalizedQueryModes,
+    tagsAll,
+    tagsAny,
+    since: body.since,
+    until: body.until,
+    categories,
+    author,
+    verify: body.verify,
+    contextBudgetTokens: body.contextBudgetTokens,
+    contextBudgetBytes: body.contextBudgetBytes,
+    maxAnswerTokens: body.maxAnswerTokens,
+  };
+  const trace = await startRestTrace(ctx, {
+    query: normalizedQuery,
+    filters: retrievalTraceFilters(askOptions),
+    pipeline: "ask",
+    modelUris: [
+      ctx.embedPort?.modelUri,
+      ctx.expandPort?.modelUri,
+      ctx.answerPort?.modelUri,
+      ctx.rerankPort?.modelUri,
+    ].filter((value): value is string => Boolean(value)),
+  });
+  if (trace.error) return trace.error;
+
+  if (!ctx.capabilities.answer) {
+    const unavailable = await trace.session?.recordCapability(
+      "answer_generation",
+      "unavailable",
+      "model_unavailable"
+    );
+    if (unavailable && !unavailable.ok) {
+      return finishRestTrace(
+        req,
+        trace.session,
+        req.signal.aborted ? "cancelled" : "failed",
+        errorResponse("RUNTIME", unavailable.error.message, 500)
+      );
+    }
+    return finishRestTrace(
+      req,
+      trace.session,
+      "failed",
+      errorResponse(
+        "UNAVAILABLE",
+        "Answer generation not available. No answer model loaded.",
+        503
+      )
+    );
+  }
+
+  if (body.verify && ctx.answerPort) {
+    try {
+      const verified = await buildVerifiedAsk(normalizedQuery, askOptions, {
+        store: ctx.store,
+        config: ctx.config,
+        indexName: ctx.indexName,
+        vectorIndex: ctx.vectorIndex,
+        embedPort: ctx.embedPort,
+        rerankPort: ctx.rerankPort,
+        genPort: ctx.answerPort,
+        traceSession: trace.session ?? undefined,
+      });
+      return finishRestTrace(
+        req,
+        trace.session,
+        answerTraceTerminalStatus(verified.citations),
+        jsonResponse(verified)
+      );
+    } catch (error) {
+      return finishRestTrace(
+        req,
+        trace.session,
+        "failed",
+        errorResponse(
+          "RUNTIME",
+          error instanceof Error ? error.message : String(error),
+          500
+        )
+      );
+    }
+  }
 
   // Run hybrid search first
   const searchResult = await searchHybrid(
@@ -3986,29 +4340,18 @@ export async function handleAsk(
     },
     normalizedQuery,
     {
-      limit,
-      collection: body.collection,
-      lang: body.lang,
-      intent: body.intent?.trim() || undefined,
-      noExpand: body.noExpand,
-      noRerank: body.noRerank,
-      candidateLimit:
-        body.candidateLimit !== undefined
-          ? Math.min(body.candidateLimit, 100)
-          : undefined,
-      exclude,
-      queryModes: normalizedQueryModes,
-      tagsAll,
-      tagsAny,
-      since: body.since,
-      until: body.until,
-      categories,
-      author,
+      ...askOptions,
+      traceSession: trace.session ?? undefined,
     }
   );
 
   if (!searchResult.ok) {
-    return errorResponse("RUNTIME", searchResult.error.message, 500);
+    return finishRestTrace(
+      req,
+      trace.session,
+      "failed",
+      errorResponse("RUNTIME", searchResult.error.message, 500)
+    );
   }
 
   const results = searchResult.value.results;
@@ -4020,20 +4363,93 @@ export async function handleAsk(
   let answerGenerated = false;
 
   if (ctx.answerPort) {
-    const maxTokens = body.maxAnswerTokens ?? 512;
-    const rawResult = await generateGroundedAnswer(
-      { genPort: ctx.answerPort, store: ctx.store },
-      normalizedQuery,
-      results,
-      maxTokens
+    const attempted = await trace.session?.recordCapability(
+      "answer_generation",
+      "attempted"
     );
+    if (attempted && !attempted.ok) {
+      return finishRestTrace(
+        req,
+        trace.session,
+        "failed",
+        errorResponse("RUNTIME", attempted.error.message, 500)
+      );
+    }
+    const maxTokens = body.maxAnswerTokens ?? 512;
+    let rawResult: Awaited<ReturnType<typeof generateGroundedAnswer>>;
+    try {
+      rawResult = await generateGroundedAnswer(
+        { genPort: ctx.answerPort, store: ctx.store },
+        normalizedQuery,
+        results,
+        maxTokens
+      );
+    } catch (error) {
+      await trace.session?.recordCapability(
+        "answer_generation",
+        "failed",
+        "generation_failed"
+      );
+      return finishRestTrace(
+        req,
+        trace.session,
+        "failed",
+        errorResponse(
+          "RUNTIME",
+          error instanceof Error ? error.message : String(error),
+          500
+        )
+      );
+    }
 
     if (rawResult) {
-      const processed = processAnswerResult(rawResult);
-      answer = processed.answer;
-      citations = processed.citations;
-      answerContext = processed.answerContext;
-      answerGenerated = true;
+      try {
+        const processed = await processAnswerResultWithTrace(
+          rawResult,
+          trace.session ?? undefined
+        );
+        answer = processed.answer;
+        citations = processed.citations;
+        answerContext = processed.answerContext;
+        answerGenerated = true;
+        const used = await trace.session?.recordCapability(
+          "answer_generation",
+          "used"
+        );
+        if (used && !used.ok) {
+          throw new Error(`Trace recording failed: ${used.error.message}`);
+        }
+      } catch (error) {
+        await trace.session?.recordCapability(
+          "answer_generation",
+          "failed",
+          "generation_failed"
+        );
+        return finishRestTrace(
+          req,
+          trace.session,
+          "failed",
+          errorResponse(
+            "RUNTIME",
+            error instanceof Error ? error.message : String(error),
+            500
+          )
+        );
+      }
+    } else {
+      const failed = await trace.session?.recordCapability(
+        "answer_generation",
+        "failed",
+        "generation_failed"
+      );
+      if (failed && !failed.ok) {
+        return finishRestTrace(
+          req,
+          trace.session,
+          "failed",
+          errorResponse("RUNTIME", failed.error.message, 500)
+        );
+      }
     }
   }
 
@@ -4058,7 +4474,13 @@ export async function handleAsk(
     },
   };
 
-  return jsonResponse(askResult);
+  const complete = answerGenerated && (citations?.length ?? 0) > 0;
+  return finishRestTrace(
+    req,
+    trace.session,
+    complete ? "completed" : "partial",
+    jsonResponse(askResult)
+  );
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -4671,7 +5093,7 @@ export async function routeApi(
   }
 
   if (path === "/api/doc") {
-    return handleDoc(store, config, url);
+    return handleDoc(store, config, url, req);
   }
 
   if (path === "/api/doc-asset") {
@@ -4679,7 +5101,25 @@ export async function routeApi(
   }
 
   if (path === "/api/search" && req.method === "POST") {
-    return handleSearch(store, req);
+    return handleSearch(
+      {
+        store,
+        config,
+        indexName: "default",
+        vectorIndex: null,
+        embedPort: null,
+        expandPort: null,
+        answerPort: null,
+        rerankPort: null,
+        capabilities: {
+          bm25: true,
+          vector: false,
+          hybrid: false,
+          answer: false,
+        },
+      },
+      req
+    );
   }
 
   // Unknown API route