@gmickel/gno 1.18.0 → 1.20.0

package/src/sdk/documents.ts

@@ -24,6 +24,11 @@ import type {
 
 import { getDocumentCapabilities } from "../core/document-capabilities";
 import { isGlobPattern, parseRef, splitRefs } from "../core/ref-parser";
+import {
+  attachRetrievalTraceMetadata,
+  evidenceFromExactDocument,
+  RetrievalTraceSession,
+} from "../core/retrieval-trace-session";
 import { sdkError } from "./errors";
 
 const URI_PREFIX_PATTERN = /^gno:\/\/[^/]+\//;
@@ -72,7 +77,7 @@ function buildConversionMeta(
   };
 }
 
-export async function getDocumentByRef(
+async function getDocumentByRefUntraced(
   store: StorePort,
   config: Config,
   ref: string,
@@ -159,6 +164,48 @@ export async function getDocumentByRef(
   };
 }
 
+export async function getDocumentByRef(
+  store: StorePort,
+  config: Config,
+  ref: string,
+  options: GnoGetOptions = {}
+): Promise<GetResponse> {
+  const response = await getDocumentByRefUntraced(store, config, ref, options);
+  if (!options.traceId) return response;
+  const resumed = await RetrievalTraceSession.resume({
+    store,
+    config: config.retrievalTraces,
+    traceId: options.traceId,
+  });
+  if (!resumed.ok) {
+    throw sdkError("STORE", resumed.error.message, {
+      cause: resumed.error.cause,
+    });
+  }
+  const traceSession = resumed.value;
+  if (!traceSession) return response;
+  const lines = response.returnedLines ?? {
+    start: 1,
+    end: response.totalLines,
+  };
+  const evidence = evidenceFromExactDocument({
+    docid: response.docid,
+    uri: response.uri,
+    sourceHash: response.source.sourceHash,
+    mirrorHash: response.conversion?.mirrorHash,
+    content: response.content,
+    startLine: lines.start,
+    endLine: lines.end,
+  });
+  if (evidence) {
+    const got = await traceSession.recordEvidence("get", [evidence]);
+    if (!got.ok) throw sdkError("STORE", got.error.message);
+    const opened = await traceSession.recordEvidence("open", [evidence]);
+    if (!opened.ok) throw sdkError("STORE", opened.error.message);
+  }
+  return attachRetrievalTraceMetadata(response, traceSession);
+}
+
 function truncateContent(
   content: string,
   maxBytes: number

package/src/sdk/index.ts

@@ -72,3 +72,20 @@ export {
   ContextRuntimeError,
   type ContextRuntimeErrorCode,
 } from "../app/context-runtime";
+export {
+  getRetrievalTraceMetadata,
+  RETRIEVAL_TRACE_METADATA,
+  type RetrievalTraceSurfaceMetadata,
+} from "../core/retrieval-trace-session";
+export type {
+  RetrievalTraceDeleteResult,
+  RetrievalTraceDetail,
+  RetrievalTraceExportRequest,
+  RetrievalTraceExportResult,
+  RetrievalTraceLabelRequest,
+  RetrievalTraceLabelResult,
+  RetrievalTraceListRequest,
+  RetrievalTraceListResult,
+  RetrievalTracePurgeResult,
+  RetrievalTraceSummary,
+} from "../core/retrieval-trace-management";

package/src/sdk/types.ts

@@ -19,6 +19,17 @@ import type { ContextEvidenceErrorCode } from "../core/context-evidence";
 import type { ContextVerifierErrorCode } from "../core/context-verifier";
 import type { NoteCollisionPolicy } from "../core/note-creation";
 import type { NotePresetId } from "../core/note-presets";
+import type {
+  RetrievalTraceDeleteResult,
+  RetrievalTraceDetail,
+  RetrievalTraceExportRequest,
+  RetrievalTraceExportResult,
+  RetrievalTraceLabelRequest,
+  RetrievalTraceLabelResult,
+  RetrievalTraceListRequest,
+  RetrievalTraceListResult,
+  RetrievalTracePurgeResult as RetrievalTraceManagementPurgeResult,
+} from "../core/retrieval-trace-management";
 import type { DocumentSection } from "../core/sections";
 import type { SyncResult } from "../ingestion";
 import type { DownloadPolicy } from "../llm/policy";
@@ -88,6 +99,8 @@ export type GnoContextErrorCode =
 export interface GnoGetOptions {
   from?: number;
   limit?: number;
+  /** Continue an open retrieval trace returned by search/query. */
+  traceId?: string;
 }
 
 export interface GnoMultiGetOptions {
@@ -221,6 +234,21 @@ export interface GnoClient {
     options?: GnoListOptions
   ): Promise<import("../cli/commands/ls").LsResponse>;
   status(): Promise<IndexStatus>;
+  listRetrievalTraces(
+    options?: RetrievalTraceListRequest
+  ): Promise<RetrievalTraceListResult>;
+  getRetrievalTrace(
+    traceId: string,
+    options?: { detailLimit?: number }
+  ): Promise<RetrievalTraceDetail>;
+  labelRetrievalTrace(
+    input: RetrievalTraceLabelRequest
+  ): Promise<RetrievalTraceLabelResult>;
+  exportRetrievalTraces(
+    input: RetrievalTraceExportRequest
+  ): Promise<RetrievalTraceExportResult>;
+  deleteRetrievalTrace(traceId: string): Promise<RetrievalTraceDeleteResult>;
+  purgeRetrievalTraces(): Promise<RetrievalTraceManagementPurgeResult>;
   update(options?: GnoUpdateOptions): Promise<SyncResult>;
   embed(options?: GnoEmbedOptions): Promise<GnoEmbedResult>;
   index(options?: GnoIndexOptions): Promise<GnoIndexResult>;

package/src/serve/context-capsule.ts

@@ -1,5 +1,6 @@
 /** REST adapters for the shared Context Capsule application boundary. */
 
+import type { RetrievalTraceSession } from "../core/retrieval-trace-session";
 import type { GnoContextErrorCode } from "../sdk/types";
 import type { ServerContext } from "./context";
 
@@ -20,6 +21,8 @@ import {
   parseContextVerifySurfaceInput,
 } from "../app/context-surface";
 import { ContextCapsuleContractError } from "../core/context-capsule";
+import { startRetrievalTraceRequest } from "../core/retrieval-trace-request";
+import { withRetrievalTraceHeader } from "./retrieval-trace";
 
 const JSON_HEADERS = { "content-type": "application/json; charset=utf-8" };
 const MARKDOWN_HEADERS = {
@@ -80,6 +83,7 @@ export const handleContextBuild = async (
   context: ServerContext,
   request: Request
 ): Promise<Response> => {
+  let traceSession: RetrievalTraceSession | null = null;
   try {
     const { input, format } = parseContextBuildSurfaceInput(
       await parseJsonBody(request),
@@ -90,6 +94,42 @@ export const handleContextBuild = async (
       context.indexName,
       context.config.collections.map((collection) => collection.name)
     );
+    const started = await startRetrievalTraceRequest({
+      store: context.store,
+      config: context.config,
+      query: input.query ?? input.goal,
+      goal: input.goal,
+      filters: {
+        limit: input.limit,
+        collection:
+          input.collections?.length === 1 ? input.collections[0] : undefined,
+        collections: [...(input.collections ?? [])].sort(),
+        lang: input.lang,
+        tagsAll: input.tagsAll,
+        tagsAny: input.tagsAny,
+        since: input.since,
+        until: input.until,
+        categories: input.categories,
+        author: input.author,
+        graph: input.graph,
+        candidateLimit: input.candidateLimit,
+        queryModes: input.queryModes,
+        uriPrefix: input.uriPrefix ?? undefined,
+      },
+      pipeline: "context",
+      indexName: context.indexName,
+      modelUris: [
+        context.embedPort?.modelUri,
+        context.rerankPort?.modelUri,
+      ].filter((value): value is string => Boolean(value)),
+    });
+    if (!started.ok) {
+      throw Object.assign(
+        new Error(`Retrieval trace start failed: ${started.error.message}`),
+        { code: "retrieval_failed" }
+      );
+    }
+    traceSession = started.value;
     const capsule = await buildContextCapsule(input, {
       store: context.store,
       config: context.config,
@@ -97,16 +137,35 @@ export const handleContextBuild = async (
       vectorIndex: context.vectorIndex,
       embedPort: context.embedPort,
       rerankPort: context.rerankPort,
+      traceSession: traceSession ?? undefined,
     });
-    return format === "md"
-      ? new Response(formatContextCapsuleMarkdown(capsule), {
-          headers: MARKDOWN_HEADERS,
-        })
-      : new Response(canonicalBuiltContextCapsuleJson(capsule), {
-          headers: JSON_HEADERS,
-        });
+    const finished = await traceSession?.finish(
+      request.signal.aborted ? "cancelled" : "completed"
+    );
+    if (finished && !finished.ok) {
+      throw Object.assign(
+        new Error(
+          `Retrieval trace finalization failed: ${finished.error.message}`
+        ),
+        { code: "retrieval_failed" }
+      );
+    }
+    const response =
+      format === "md"
+        ? new Response(formatContextCapsuleMarkdown(capsule), {
+            headers: MARKDOWN_HEADERS,
+          })
+        : new Response(canonicalBuiltContextCapsuleJson(capsule), {
+            headers: JSON_HEADERS,
+          });
+    return withRetrievalTraceHeader(response, traceSession);
   } catch (error) {
-    return errorResponse(error);
+    if (traceSession) {
+      await traceSession.finish(
+        request.signal.aborted ? "cancelled" : "failed"
+      );
+    }
+    return withRetrievalTraceHeader(errorResponse(error), traceSession);
   }
 };
 

package/src/serve/public/app.tsx

@@ -29,6 +29,7 @@ import DocumentEditor from "./pages/DocumentEditor";
 import DocView from "./pages/DocView";
 import GraphView from "./pages/GraphView";
 import Search from "./pages/Search";
+import TraceHistory from "./pages/TraceHistory";
 
 type Route =
   | "/"
@@ -39,7 +40,8 @@ type Route =
   | "/edit"
   | "/collections"
   | "/graph"
-  | "/connectors";
+  | "/connectors"
+  | "/traces";
 type Navigate = (to: string | number) => void;
 
 interface RoutePageProps {
@@ -57,6 +59,7 @@ const routes: Record<Route, React.ComponentType<RoutePageProps>> = {
   "/connectors": Connectors,
   "/ask": Ask,
   "/graph": GraphView,
+  "/traces": TraceHistory,
 };
 
 interface AppContentProps {
@@ -165,6 +168,14 @@ function AppContent({
               Collections
             </button>
             <span className="text-border/30">—</span>
+            <button
+              className="transition-colors duration-300 hover:text-primary"
+              onClick={() => navigate("/traces")}
+              type="button"
+            >
+              Trace history
+            </button>
+            <span className="text-border/30">—</span>
             <a
               className="transition-colors duration-300 hover:text-primary"
               href="https://github.com/gmickel/gno"

package/src/serve/public/components/AskVerificationPanel.tsx

@@ -0,0 +1,189 @@
+import { AlertTriangle, CheckCircle2, CircleHelp, ShieldX } from "lucide-react";
+
+import type { AskResult } from "../../../pipeline/types";
+
+import { cn } from "../lib/utils";
+import { Badge } from "./ui/badge";
+
+export type AskVerification = NonNullable<AskResult["verification"]>;
+
+interface AskVerificationPanelProps {
+  navigate: (to: string) => void;
+  verification: AskVerification;
+}
+
+const STATUS_PRESENTATION = {
+  supported: {
+    label: "supported",
+    icon: CheckCircle2,
+    className: "border-emerald-500/30 bg-emerald-500/10 text-emerald-300",
+  },
+  contradicted: {
+    label: "contradicted",
+    icon: ShieldX,
+    className: "border-destructive/40 bg-destructive/10 text-destructive",
+  },
+  insufficient: {
+    label: "insufficient",
+    icon: AlertTriangle,
+    className: "border-amber-500/30 bg-amber-500/10 text-amber-300",
+  },
+  uncertain: {
+    label: "uncertain",
+    icon: CircleHelp,
+    className: "border-sky-500/30 bg-sky-500/10 text-sky-300",
+  },
+} as const;
+
+const evidenceLabel = (uri: string, startLine: number, endLine: number) =>
+  `${uri}:L${startLine}${startLine === endLine ? "" : `-L${endLine}`}`;
+
+export function AskVerificationPanel({
+  navigate,
+  verification,
+}: AskVerificationPanelProps) {
+  const { claims, capsule, semantic } = verification;
+  const degradedCapabilities = Object.entries(
+    capsule.retrieval.capabilityStates
+  ).filter(([, state]) => state.requested && state.outcome !== "used");
+  const gaps = capsule.coverage.gaps;
+
+  return (
+    <details className="group rounded-lg border border-border/50 bg-card/55">
+      <summary className="flex cursor-pointer list-none items-center justify-between gap-3 px-4 py-3">
+        <div className="min-w-0">
+          <div className="flex flex-wrap items-center gap-2">
+            <span className="font-medium text-sm">
+              {claims.answerStatus === "verified"
+                ? "All claims verified"
+                : "Answer withheld"}
+            </span>
+            <Badge
+              className="font-mono text-[9px]"
+              variant={
+                claims.answerStatus === "verified" ? "default" : "outline"
+              }
+            >
+              {claims.coverage.supportedClaims}/{claims.coverage.totalClaims}{" "}
+              supported
+            </Badge>
+          </div>
+          <p className="mt-1 text-muted-foreground text-xs">
+            {claims.abstentionReason ??
+              `${claims.coverage.supportedRatio * 100}% support coverage`}
+          </p>
+        </div>
+        <span className="shrink-0 font-mono text-[10px] text-muted-foreground group-open:hidden">
+          details
+        </span>
+      </summary>
+
+      <div className="space-y-4 border-border/40 border-t px-4 py-4">
+        <div className="flex flex-wrap gap-2">
+          <Badge className="font-mono text-[9px]" variant="outline">
+            semantic: {semantic.status}/{semantic.reason}
+          </Badge>
+          {degradedCapabilities.map(([name, state]) => (
+            <Badge
+              className="font-mono text-[9px]"
+              key={name}
+              variant="outline"
+            >
+              {name}: {state.outcome}
+              {state.fallbackReasons.length > 0
+                ? ` (${state.fallbackReasons.join(", ")})`
+                : ""}
+            </Badge>
+          ))}
+        </div>
+
+        <div className="grid grid-cols-2 gap-2 font-mono text-[10px] text-muted-foreground sm:grid-cols-4">
+          <span>{claims.coverage.supportedClaims} supported</span>
+          <span>{claims.coverage.contradictedClaims} contradicted</span>
+          <span>{claims.coverage.insufficientClaims} insufficient</span>
+          <span>{claims.coverage.uncertainClaims} uncertain</span>
+        </div>
+
+        <div className="space-y-2">
+          {claims.claims.map((claim) => {
+            const presentation = STATUS_PRESENTATION[claim.status];
+            const StatusIcon = presentation.icon;
+            return (
+              <details
+                className="rounded-md border border-border/35 bg-background/20"
+                key={claim.claimId}
+              >
+                <summary className="flex cursor-pointer list-none items-start gap-2 px-3 py-2">
+                  <StatusIcon className="mt-0.5 size-3.5 shrink-0" />
+                  <span className="min-w-0 flex-1 text-xs">{claim.text}</span>
+                  <Badge
+                    className={cn(
+                      "shrink-0 font-mono text-[9px]",
+                      presentation.className
+                    )}
+                    variant="outline"
+                  >
+                    {presentation.label}
+                  </Badge>
+                </summary>
+                <div className="space-y-2 border-border/30 border-t px-3 py-2">
+                  {claim.evidence.length > 0 ? (
+                    claim.evidence.map((evidence) => (
+                      <button
+                        className="block w-full truncate text-left font-mono text-[10px] text-primary hover:underline"
+                        key={evidence.evidenceId}
+                        onClick={() =>
+                          navigate(
+                            `/doc?uri=${encodeURIComponent(evidence.uri)}`
+                          )
+                        }
+                        title={evidenceLabel(
+                          evidence.uri,
+                          evidence.startLine,
+                          evidence.endLine
+                        )}
+                        type="button"
+                      >
+                        {evidenceLabel(
+                          evidence.uri,
+                          evidence.startLine,
+                          evidence.endLine
+                        )}
+                      </button>
+                    ))
+                  ) : (
+                    <p className="text-muted-foreground text-xs">
+                      No retained evidence span.
+                    </p>
+                  )}
+                  <p className="font-mono text-[10px] text-muted-foreground">
+                    {claim.rationaleCode}
+                    {claim.confidence === null
+                      ? ""
+                      : ` · confidence ${claim.confidence.toFixed(2)}`}
+                  </p>
+                </div>
+              </details>
+            );
+          })}
+        </div>
+
+        {(capsule.coverage.unresolvedFacets.length > 0 || gaps.length > 0) && (
+          <div className="rounded-md border border-amber-500/25 bg-amber-500/5 px-3 py-2">
+            <p className="font-medium text-amber-200 text-xs">Evidence gaps</p>
+            <ul className="mt-1 space-y-1 font-mono text-[10px] text-muted-foreground">
+              {capsule.coverage.unresolvedFacets.map((facet) => (
+                <li key={`facet:${facet}`}>unresolved facet: {facet}</li>
+              ))}
+              {gaps.map((gap) => (
+                <li key={`${gap.facet}:${gap.code}`}>
+                  {gap.facet}: {gap.code}
+                </li>
+              ))}
+            </ul>
+          </div>
+        )}
+      </div>
+    </details>
+  );
+}