@gmickel/gno 1.19.0 → 1.21.0

package/src/serve/public/pages/Ask.tsx

@@ -21,6 +21,10 @@ import {
   SourcesTrigger,
 } from "../components/ai-elements/sources";
 import { AIModelSelector } from "../components/AIModelSelector";
+import {
+  type AskVerification,
+  AskVerificationPanel,
+} from "../components/AskVerificationPanel";
 import {
   ThoroughnessSelector,
   type Thoroughness,
@@ -57,6 +61,7 @@ interface PageProps {
 }
 
 interface Citation {
+  evidenceId?: string;
   docid: string;
   uri: string;
   startLine?: number;
@@ -88,12 +93,15 @@ interface AskResponse {
     vectorsUsed: boolean;
     answerGenerated: boolean;
     totalResults: number;
+    verificationRequested?: boolean;
+    abstained?: boolean;
     queryModes?: {
       term: number;
       intent: number;
       hyde: boolean;
     };
   };
+  verification?: AskVerification;
 }
 
 interface Capabilities {
@@ -139,7 +147,7 @@ function renderAnswer(
   const parts: React.ReactNode[] = [];
   let key = 0;
 
-  const citationRegex = /\[(\d+)\]/g;
+  const citationRegex = /\[(?:evidence:([a-f0-9]{64})|(\d+))\]/g;
   let lastIndex = 0;
   let match: RegExpExecArray | null;
 
@@ -149,8 +157,13 @@ function renderAnswer(
       parts.push(answer.slice(lastIndex, match.index));
     }
 
-    const citationNum = Number(match[1]);
-    const citation = citations[citationNum - 1];
+    const evidenceId = match[1];
+    const numericCitation = match[2] ? Number(match[2]) : undefined;
+    const citationIndex = evidenceId
+      ? citations.findIndex((citation) => citation.evidenceId === evidenceId)
+      : (numericCitation ?? 0) - 1;
+    const citationNum = citationIndex + 1;
+    const citation = citations[citationIndex];
 
     if (citation) {
       parts.push(
@@ -186,6 +199,7 @@ export default function Ask({ navigate }: PageProps) {
   const [collections, setCollections] = useState<Collection[]>([]);
   const [thoroughness, setThoroughness] = useState<Thoroughness>("balanced");
   const [activePreset, setActivePreset] = useState("slim-tuned");
+  const [verify, setVerify] = useState(false);
 
   const [showAdvanced, setShowAdvanced] = useState(false);
   const [selectedCollection, setSelectedCollection] = useState("");
@@ -318,6 +332,7 @@ export default function Ask({ navigate }: PageProps) {
       const requestBody: Record<string, unknown> = {
         query: currentQuery,
         limit: 5,
+        verify,
       };
 
       if (selectedCollection) {
@@ -394,6 +409,7 @@ export default function Ask({ navigate }: PageProps) {
       tagsInput,
       thoroughness,
       until,
+      verify,
     ]
   );
 
@@ -443,6 +459,7 @@ export default function Ask({ navigate }: PageProps) {
     parseTagsCsv(tagsInput).length > 0
       ? `${tagMode}:${parseTagsCsv(tagsInput).join(",")}`
       : null,
+    verify ? "verified" : null,
   ].filter((pill): pill is string => Boolean(pill));
 
   return (
@@ -475,6 +492,16 @@ export default function Ask({ navigate }: PageProps) {
               value={thoroughness}
             />
 
+            <Button
+              aria-pressed={verify}
+              onClick={() => setVerify((value) => !value)}
+              size="sm"
+              type="button"
+              variant={verify ? "default" : "outline"}
+            >
+              Verify
+            </Button>
+
             <div className="h-6 w-px bg-border/40" />
 
             <AIModelSelector onPresetChange={setActivePreset} />
@@ -878,8 +905,19 @@ export default function Ask({ navigate }: PageProps) {
                         </Sources>
                       )}
 
+                    {entry.response.verification && (
+                      <AskVerificationPanel
+                        navigate={navigate}
+                        verification={entry.response.verification}
+                      />
+                    )}
+
                     <div className="flex items-center gap-2 text-muted-foreground/60 text-xs">
-                      <span>{entry.response.results.length} results</span>
+                      <span>
+                        {entry.response.verification
+                          ? `${entry.response.verification.capsule.evidence.length} evidence spans`
+                          : `${entry.response.results.length} results`}
+                      </span>
                       {entry.response.meta.vectorsUsed && (
                         <Badge
                           className="font-mono text-[9px]"

package/src/serve/resident-runtime.ts

@@ -31,6 +31,7 @@ import {
   isInitialized,
   loadConfig,
 } from "../config";
+import { SavedCapsuleReverificationScheduler } from "../core/capsule-reverification-scheduler";
 import { acquireWriteLock } from "../core/file-lock";
 import { JobManager } from "../core/job-manager";
 import { recordContentMutation } from "../core/mutation-generations";
@@ -94,6 +95,7 @@ export interface ResidentRuntime {
   readonly toolMutex: Mutex;
   readonly readerGate: ReaderGate;
   readonly jobManager: JobManager;
+  readonly capsuleReverificationScheduler: SavedCapsuleReverificationScheduler;
   readonly modelManager: ModelManager;
   readonly mcpContext: ToolContext;
   readonly generations: ResidentGeneration;
@@ -266,6 +268,8 @@ export async function startResidentRuntime(
   ctxHolder.current.scheduler = scheduler;
   ctxHolder.current.eventBus = options.eventBus ?? null;
 
+  let capsuleReverificationScheduler: SavedCapsuleReverificationScheduler | null =
+    null;
   const watchService = (
     deps.watchServiceFactory ??
     ((watchOptions) => new DefaultCollectionWatchService(watchOptions))
@@ -282,6 +286,10 @@ export async function startResidentRuntime(
         });
         options.watchCallbacks?.onSyncComplete?.(event);
       },
+      onSettled: () => {
+        capsuleReverificationScheduler?.notifySyncSettled();
+        options.watchCallbacks?.onSettled?.();
+      },
     },
     syncOptions: withContentTypeRules({}, initialConfig),
   });
@@ -312,6 +320,17 @@ export async function startResidentRuntime(
   const backgroundWork = new ResidentBackgroundWork(
     () => !disposed && admission.accepting
   );
+  capsuleReverificationScheduler = new SavedCapsuleReverificationScheduler({
+    deps: {
+      store,
+      get config() {
+        return ctxHolder.config;
+      },
+      indexName: canonicalizeIndexName(options.index ?? DEFAULT_INDEX_NAME),
+      notify: (event) => options.eventBus?.emit(event),
+    },
+    startBackgroundWork: (operation) => backgroundWork.start(operation),
+  });
 
   const mcpContext = createToolContext({
     store,
@@ -355,6 +374,7 @@ export async function startResidentRuntime(
     toolMutex,
     readerGate,
     jobManager,
+    capsuleReverificationScheduler,
     modelManager,
     mcpContext,
     generations,
@@ -453,6 +473,7 @@ export async function startResidentRuntime(
         syncOptions.triggerEmbed === false
           ? null
           : await scheduler.triggerNow();
+      capsuleReverificationScheduler.notifySyncSettled();
       return { syncResult, embedResult };
     },
     async dispose() {
@@ -466,6 +487,7 @@ export async function startResidentRuntime(
       );
       if (deadlineReached) shutdownState = "deadline";
       await backgroundWork.cancelAndDrain();
+      await capsuleReverificationScheduler.dispose();
       await jobManager.shutdown().catch(() => undefined);
       await Promise.allSettled([
         Promise.resolve().then(() => watchService.dispose()),

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,
@@ -125,6 +126,7 @@ import {
   resolveModelUri,
 } from "../../llm/registry";
 import {
+  answerTraceTerminalStatus,
   generateGroundedAnswer,
   processAnswerResultWithTrace,
 } from "../../pipeline/answer";
@@ -158,6 +160,7 @@ import {
   withRetrievalTraceHeader,
 } from "../retrieval-trace";
 import { buildAppStatus, type StatusBuildDeps } from "../status";
+import { handleChanges, handleDiff, handleImpact } from "./changes";
 
 /** Mutable context holder for hot-reloading presets */
 export interface ContextHolder {
@@ -289,14 +292,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;
@@ -512,11 +547,12 @@ async function startRestTrace(
 async function finishRestTrace(
   request: Request,
   session: RetrievalTraceSession | null,
-  status: "completed" | "partial" | "failed",
+  status: "completed" | "partial" | "failed" | "cancelled",
   response: Response
 ): Promise<Response> {
   if (!session) return response;
-  const terminalStatus = request.signal.aborted ? "cancelled" : status;
+  const terminalStatus =
+    request.signal.aborted || status === "cancelled" ? "cancelled" : status;
   const finished = await session.finish(terminalStatus);
   if (!finished.ok) {
     return withRetrievalTraceHeader(
@@ -3503,6 +3539,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");
   }
@@ -4028,15 +4067,84 @@ 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");
   }
 
+  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(
+      "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"
+    );
+  }
+
   // Parse tag filters
   let tagsAll: string[] | undefined;
   let tagsAny: string[] | undefined;
@@ -4128,6 +4236,7 @@ export async function handleAsk(
     collection: body.collection,
     lang: body.lang,
     intent: body.intent?.trim() || undefined,
+    minScore: body.minScore,
     noExpand: body.noExpand,
     noRerank: body.noRerank,
     candidateLimit:
@@ -4135,6 +4244,8 @@ export async function handleAsk(
         ? Math.min(body.candidateLimit, 100)
         : undefined,
     exclude,
+    graph: body.graph,
+    noGraph: body.noGraph,
     queryModes: normalizedQueryModes,
     tagsAll,
     tagsAny,
@@ -4142,6 +4253,10 @@ export async function handleAsk(
     until: body.until,
     categories,
     author,
+    verify: body.verify,
+    contextBudgetTokens: body.contextBudgetTokens,
+    contextBudgetBytes: body.contextBudgetBytes,
+    maxAnswerTokens: body.maxAnswerTokens,
   };
   const trace = await startRestTrace(ctx, {
     query: normalizedQuery,
@@ -4166,7 +4281,7 @@ export async function handleAsk(
       return finishRestTrace(
         req,
         trace.session,
-        "failed",
+        req.signal.aborted ? "cancelled" : "failed",
         errorResponse("RUNTIME", unavailable.error.message, 500)
       );
     }
@@ -4182,6 +4297,38 @@ export async function handleAsk(
     );
   }
 
+  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(
     {
@@ -4976,6 +5123,18 @@ export async function routeApi(
     );
   }
 
+  if (path === "/api/changes" && req.method === "GET") {
+    return handleChanges(store, url);
+  }
+
+  if (path === "/api/diff" && req.method === "GET") {
+    return handleDiff(store, url);
+  }
+
+  if (path === "/api/impact" && req.method === "GET") {
+    return handleImpact(store, url);
+  }
+
   // Unknown API route
   if (path.startsWith("/api/")) {
     return errorResponse("NOT_FOUND", `Unknown API endpoint: ${path}`, 404);

package/src/serve/routes/changes.ts

@@ -0,0 +1,102 @@
+/** Read-only REST handlers for knowledge change, diff, and impact services. */
+
+import type { KnowledgeImpactInput } from "../../core/knowledge-delta";
+import type { StorePort } from "../../store/types";
+
+import {
+  analyzeKnowledgeImpact,
+  getKnowledgeDiff,
+  listKnowledgeChanges,
+} from "../../core/knowledge-delta";
+
+const errorResponse = (
+  code: "VALIDATION" | "RUNTIME",
+  message: string
+): Response =>
+  Response.json(
+    { error: { code, message } },
+    { status: code === "VALIDATION" ? 400 : 500 }
+  );
+
+const parsePositiveInt = (
+  url: URL,
+  name: string
+): number | undefined | Response => {
+  const raw = url.searchParams.get(name);
+  if (raw === null) return;
+  if (!/^\d+$/.test(raw)) {
+    return errorResponse("VALIDATION", `${name} must be a positive integer`);
+  }
+  const value = Number(raw);
+  return Number.isSafeInteger(value) && value > 0
+    ? value
+    : errorResponse("VALIDATION", `${name} must be a positive integer`);
+};
+
+export async function handleChanges(
+  store: StorePort,
+  url: URL
+): Promise<Response> {
+  const limit = parsePositiveInt(url, "limit");
+  if (limit instanceof Response) return limit;
+  const result = await listKnowledgeChanges(store, {
+    since: url.searchParams.get("since") ?? undefined,
+    collection: url.searchParams.get("collection") ?? undefined,
+    limit,
+  });
+  if (!result.success) {
+    return errorResponse(
+      result.isValidation ? "VALIDATION" : "RUNTIME",
+      result.error
+    );
+  }
+  return Response.json(result.data);
+}
+
+export async function handleDiff(
+  store: StorePort,
+  url: URL
+): Promise<Response> {
+  const ref = url.searchParams.get("ref")?.trim();
+  if (!ref) return errorResponse("VALIDATION", "ref is required");
+  const result = await getKnowledgeDiff(
+    store,
+    ref,
+    url.searchParams.get("change") ?? undefined
+  );
+  if (!result.success) {
+    return errorResponse(
+      result.isValidation ? "VALIDATION" : "RUNTIME",
+      result.error
+    );
+  }
+  return Response.json(result.data);
+}
+
+export async function handleImpact(
+  store: StorePort,
+  url: URL
+): Promise<Response> {
+  const ref = url.searchParams.get("ref")?.trim();
+  if (!ref) return errorResponse("VALIDATION", "ref is required");
+  const input: KnowledgeImpactInput = {};
+  for (const [queryName, inputName] of [
+    ["maxDepth", "maxDepth"],
+    ["maxNodes", "maxNodes"],
+    ["maxEdges", "maxEdges"],
+    ["frontierLimit", "frontierLimit"],
+    ["visitedLimit", "visitedLimit"],
+  ] as const) {
+    const value = parsePositiveInt(url, queryName);
+    if (value instanceof Response) return value;
+    if (value !== undefined) input[inputName] = value;
+  }
+  const result = await analyzeKnowledgeImpact(store, ref, input);
+  if (!result.success) {
+    return errorResponse(
+      result.isValidation ? "VALIDATION" : "RUNTIME",
+      result.error
+    );
+  }
+  return Response.json(result.data);
+}

package/src/serve/server.ts

@@ -69,6 +69,7 @@ import {
   handleUpdateDoc,
   handleVerifyConnector,
 } from "./routes/api";
+import { handleChanges, handleDiff, handleImpact } from "./routes/changes";
 import { handleGraph, handleGraphQuery } from "./routes/graph";
 import {
   handleDocBacklinks,
@@ -968,6 +969,39 @@ export async function startServer(
             );
           },
         },
+        "/api/changes": {
+          GET: async (req: Request) => {
+            const url = new URL(req.url);
+            return withSecurityHeaders(
+              await handleResidentRead(runtime as ResidentRuntime, req, () =>
+                handleChanges(store, url)
+              ),
+              isDev
+            );
+          },
+        },
+        "/api/diff": {
+          GET: async (req: Request) => {
+            const url = new URL(req.url);
+            return withSecurityHeaders(
+              await handleResidentRead(runtime as ResidentRuntime, req, () =>
+                handleDiff(store, url)
+              ),
+              isDev
+            );
+          },
+        },
+        "/api/impact": {
+          GET: async (req: Request) => {
+            const url = new URL(req.url);
+            return withSecurityHeaders(
+              await handleResidentRead(runtime as ResidentRuntime, req, () =>
+                handleImpact(store, url)
+              ),
+              isDev
+            );
+          },
+        },
       },
     });
   } catch (e) {

package/src/serve/watch-service.ts

@@ -31,6 +31,8 @@ export interface CollectionWatchCallbacks {
     relPaths: string[];
     error: unknown;
   }) => void;
+  /** Fires after all watcher syncs and queued paths have settled. */
+  onSettled?: () => void;
 }
 
 interface CollectionWatchServiceOptions {
@@ -236,6 +238,13 @@ export class CollectionWatchService {
       const remaining = this.#pendingByCollection.get(collectionName);
       if (remaining && remaining.size > 0) {
         void this.#flushCollection(collectionName);
+      } else if (
+        this.#syncing.size === 0 &&
+        ![...this.#pendingByCollection.values()].some(
+          (relPaths) => relPaths.size > 0
+        )
+      ) {
+        this.#callbacks?.onSettled?.();
       }
     }
   }

package/src/store/index.ts

@@ -33,6 +33,16 @@ export type {
   CollectionRow,
   CollectionStatus,
   ContextRow,
+  DocumentChangeDateDelta,
+  DocumentChangeKind,
+  DocumentChangeListOptions,
+  DocumentChangePage,
+  DocumentChangePurgeResult,
+  DocumentChangeRetentionPolicy,
+  DocumentChangeRetentionResult,
+  DocumentChangeRow,
+  DocumentChangeSet,
+  DocumentChangeStructureDelta,
   DocumentInput,
   DocumentRow,
   FtsResult,
@@ -72,6 +82,17 @@ export type {
   RetrievalTraceRunRow,
   RetrievalTraceStatus,
   RetrievalTraceTerminalStatus,
+  RenameDocumentOptions,
+  SavedCapsuleAffectedQuestionState,
+  SavedCapsuleEvidenceReference,
+  SavedCapsuleNotificationPreference,
+  SavedCapsuleOperationStatus,
+  SavedCapsuleRegistration,
+  SavedCapsuleRegistrationInput,
+  SavedCapsuleRegistrationRecord,
+  SavedCapsuleReverificationState,
+  SavedCapsuleTriggerKind,
+  SavedCapsuleVerificationRecord,
   StoreError,
   StoreErrorCode,
   StorePort,