@gmickel/gno 1.19.0 → 1.20.0

package/src/llm/nodeLlamaCpp/generation.ts

@@ -18,6 +18,39 @@ type LlamaModel = Awaited<
     Awaited<ReturnType<typeof import("node-llama-cpp").getLlama>>["loadModel"]
   >
 >;
+type Llama = Awaited<ReturnType<typeof import("node-llama-cpp").getLlama>>;
+type JsonGrammarSchema = Parameters<Llama["createGrammarForJsonSchema"]>[0];
+
+export interface JsonSchemaGrammarLike {
+  parse(response: string): unknown;
+}
+
+export interface StructuredPromptSession {
+  prompt(
+    prompt: string,
+    options: {
+      temperature: number;
+      seed: number;
+      maxTokens: number;
+      grammar?: JsonSchemaGrammarLike;
+    }
+  ): Promise<string>;
+}
+
+export const promptWithJsonSchemaGrammar = async (
+  session: StructuredPromptSession,
+  prompt: string,
+  options: {
+    temperature: number;
+    seed: number;
+    maxTokens: number;
+  },
+  grammar?: JsonSchemaGrammarLike
+): Promise<string> => {
+  const response = await session.prompt(prompt, { ...options, grammar });
+  grammar?.parse(response);
+  return response;
+};
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Default Parameters (for determinism)
@@ -34,6 +67,7 @@ const DEFAULT_MAX_TOKENS = 256;
 export class NodeLlamaCppGeneration implements GenerationPort {
   private readonly manager: ModelManager;
   readonly modelUri: string;
+  readonly structuredOutput = "json_schema" as const;
   private readonly modelPath: string;
 
   constructor(manager: ModelManager, modelUri: string, modelPath: string) {
@@ -56,11 +90,16 @@ export class NodeLlamaCppGeneration implements GenerationPort {
     }
 
     const llamaModel = model.value.model as LlamaModel;
-    const context = await llamaModel.createContext(
-      params?.contextSize ? { contextSize: params.contextSize } : undefined
-    );
-
+    let context: Awaited<ReturnType<LlamaModel["createContext"]>> | null = null;
     try {
+      const grammar = params?.jsonSchema
+        ? await (
+            await this.manager.getLlama()
+          ).createGrammarForJsonSchema(params.jsonSchema as JsonGrammarSchema)
+        : undefined;
+      context = await llamaModel.createContext(
+        params?.contextSize ? { contextSize: params.contextSize } : undefined
+      );
       // Import LlamaChatSession dynamically
       const { LlamaChatSession } = await import("node-llama-cpp");
       const session = new LlamaChatSession({
@@ -68,17 +107,22 @@ export class NodeLlamaCppGeneration implements GenerationPort {
       });
 
       // Note: stop sequences not yet supported - requires stopOnTrigger API
-      const response = await session.prompt(prompt, {
-        temperature: params?.temperature ?? DEFAULT_TEMPERATURE,
-        seed: params?.seed ?? DEFAULT_SEED,
-        maxTokens: params?.maxTokens ?? DEFAULT_MAX_TOKENS,
-      });
+      const response = await promptWithJsonSchemaGrammar(
+        session as StructuredPromptSession,
+        prompt,
+        {
+          temperature: params?.temperature ?? DEFAULT_TEMPERATURE,
+          seed: params?.seed ?? DEFAULT_SEED,
+          maxTokens: params?.maxTokens ?? DEFAULT_MAX_TOKENS,
+        },
+        grammar
+      );
 
       return { ok: true, value: response };
     } catch (e) {
       return { ok: false, error: inferenceFailedError(this.modelUri, e) };
     } finally {
-      await context.dispose().catch(() => {
+      await context?.dispose().catch(() => {
         // Ignore disposal errors
       });
     }

package/src/llm/types.ts

@@ -58,8 +58,12 @@ export interface GenParams {
   contextSize?: number;
   /** Stop sequences */
   stop?: string[];
+  /** Closed JSON Schema enforced by a capable generation backend. */
+  jsonSchema?: Readonly<Record<string, unknown>>;
 }
 
+export type StructuredOutputCapability = "json_schema" | "none";
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Rerank Types
 // ─────────────────────────────────────────────────────────────────────────────
@@ -90,6 +94,8 @@ export interface EmbeddingPort {
 
 export interface GenerationPort {
   readonly modelUri: string;
+  /** Undefined is treated as unsupported for backwards-compatible ports. */
+  readonly structuredOutput?: StructuredOutputCapability;
   generate(prompt: string, params?: GenParams): Promise<LlmResult<string>>;
   dispose(): Promise<void>;
 }

package/src/mcp/tools/ask.ts

@@ -0,0 +1,228 @@
+/** MCP verified Ask tool over the shared closed-evidence application boundary. */
+
+import { z } from "zod";
+
+import type { RetrievalTraceSession } from "../../core/retrieval-trace-session";
+import type { QueryModeInput } from "../../pipeline/types";
+import type { ToolContext } from "../server";
+import type { ToolResult } from "./index";
+
+import { buildVerifiedAsk } from "../../app/verified-ask";
+import {
+  finishRetrievalTraceAfterError,
+  retrievalTraceFilters,
+  startRetrievalTraceRequest,
+} from "../../core/retrieval-trace-request";
+import { attachRetrievalTraceMetadata } from "../../core/retrieval-trace-session";
+import { normalizeStructuredQueryInput } from "../../core/structured-query";
+import { resolveModelUri } from "../../llm/registry";
+import { answerTraceTerminalStatus } from "../../pipeline/answer";
+import { createMcpModelPorts, type McpModelPortFactory } from "./context";
+import { normalizeTagFilters, runTool } from "./index";
+
+const queryModeSchema = z
+  .object({
+    mode: z.enum(["term", "intent", "hyde"]),
+    text: z.string().trim().min(1),
+  })
+  .strict();
+
+export const askInputSchema = z
+  .object({
+    query: z.string().trim().min(1),
+    verify: z.literal(true),
+    collection: z.string().optional(),
+    limit: z.number().int().min(1).max(100).default(5),
+    minScore: z.number().min(0).max(1).optional(),
+    lang: z.string().optional(),
+    intent: z.string().optional(),
+    candidateLimit: z.number().int().min(1).max(100).optional(),
+    exclude: z.array(z.string()).optional(),
+    queryModes: z.array(queryModeSchema).optional(),
+    tagsAll: z.array(z.string()).optional(),
+    tagsAny: z.array(z.string()).optional(),
+    since: z.string().optional(),
+    until: z.string().optional(),
+    categories: z.array(z.string()).optional(),
+    author: z.string().optional(),
+    graph: z.boolean().optional(),
+    noGraph: z.boolean().optional(),
+    noRerank: z.boolean().optional(),
+    maxAnswerTokens: z.number().int().positive().optional(),
+    contextBudgetTokens: z.number().int().positive().optional(),
+    contextBudgetBytes: z.number().int().positive().optional(),
+  })
+  .strict();
+
+type AskInput = z.infer<typeof askInputSchema>;
+
+export interface HandleAskDependencies {
+  modelPortFactory?: McpModelPortFactory;
+}
+
+const exactSpan = (uri: string, startLine: number, endLine: number): string =>
+  `${uri}:L${startLine}${startLine === endLine ? "" : `-L${endLine}`}`;
+
+export const formatVerifiedAskReadable = (
+  result: Awaited<ReturnType<typeof buildVerifiedAsk>>
+): string => {
+  const numbers = new Map(
+    (result.citations ?? []).flatMap((citation, index) =>
+      citation.evidenceId ? [[citation.evidenceId, index + 1] as const] : []
+    )
+  );
+  const answer = (result.answer ?? "").replace(
+    /\[evidence:([a-f0-9]{64})\]/g,
+    (_marker, evidenceId: string) => {
+      const number = numbers.get(evidenceId);
+      return number === undefined ? "" : `[${number}]`;
+    }
+  );
+  const claims = result.verification?.claims;
+  const lines = [
+    answer || "No verified answer.",
+    "",
+    `Verification: ${claims?.answerStatus ?? "unavailable"}`,
+  ];
+  if (claims?.abstentionReason) {
+    lines.push(`Reason: ${claims.abstentionReason}`);
+  }
+  if (claims) {
+    lines.push(
+      `Claims: ${claims.coverage.supportedClaims}/${claims.coverage.totalClaims} supported`
+    );
+  }
+  const semantic = result.verification?.semantic;
+  if (semantic) {
+    lines.push(`Semantic verifier: ${semantic.status} (${semantic.reason})`);
+  }
+  for (const claim of claims?.claims ?? []) {
+    lines.push(`- ${claim.status}: ${claim.text}`);
+    for (const evidence of claim.evidence) {
+      lines.push(
+        `  ${exactSpan(evidence.uri, evidence.startLine, evidence.endLine)} (${evidence.evidenceId})`
+      );
+    }
+  }
+  for (const gap of result.verification?.capsule.coverage.gaps ?? []) {
+    lines.push(`Gap: ${gap.facet} (${gap.code})`);
+  }
+  for (const facet of result.verification?.capsule.coverage.unresolvedFacets ??
+    []) {
+    lines.push(`Unresolved facet: ${facet}`);
+  }
+  for (const [name, state] of Object.entries(
+    result.verification?.capsule.retrieval.capabilityStates ?? {}
+  )) {
+    if (state.requested && state.outcome !== "used") {
+      lines.push(
+        `Capability: ${name} ${state.outcome}${state.fallbackReasons.length > 0 ? ` (${state.fallbackReasons.join(", ")})` : ""}`
+      );
+    }
+  }
+  for (const [index, citation] of (result.citations ?? []).entries()) {
+    const span =
+      citation.startLine === undefined || citation.endLine === undefined
+        ? citation.uri
+        : exactSpan(citation.uri, citation.startLine, citation.endLine);
+    lines.push(`[${index + 1}] ${span} (${citation.evidenceId ?? "unknown"})`);
+  }
+  return lines.join("\n");
+};
+
+export const handleAsk = (
+  args: AskInput,
+  context: ToolContext,
+  dependencies: HandleAskDependencies = {}
+): Promise<ToolResult> =>
+  runTool(
+    context,
+    "gno_ask",
+    async () => {
+      if (
+        args.collection &&
+        !context.collections.some(
+          (collection) => collection.name === args.collection
+        )
+      ) {
+        throw new Error(`Collection not found: ${args.collection}`);
+      }
+      const normalized = normalizeStructuredQueryInput(
+        args.query,
+        (args.queryModes ?? []) as QueryModeInput[]
+      );
+      if (!normalized.ok) throw new Error(normalized.error.message);
+      const query = normalized.value.query;
+      const options = {
+        ...args,
+        queryModes:
+          normalized.value.queryModes.length > 0
+            ? normalized.value.queryModes
+            : undefined,
+        tagsAll: normalizeTagFilters(args.tagsAll),
+        tagsAny: normalizeTagFilters(args.tagsAny),
+      };
+      let traceSession: RetrievalTraceSession | undefined;
+      let modelPorts: Awaited<ReturnType<typeof createMcpModelPorts>> | null =
+        null;
+      try {
+        const started = await startRetrievalTraceRequest({
+          store: context.store,
+          config: context.config,
+          query,
+          filters: retrievalTraceFilters(options),
+          pipeline: "ask",
+          indexName: context.indexName,
+          modelUris: [
+            resolveModelUri(
+              context.config,
+              "embed",
+              undefined,
+              args.collection
+            ),
+            resolveModelUri(
+              context.config,
+              "rerank",
+              undefined,
+              args.collection
+            ),
+            resolveModelUri(context.config, "gen", undefined, args.collection),
+          ],
+        });
+        if (!started.ok) throw new Error(started.error.message);
+        traceSession = started.value ?? undefined;
+        modelPorts = await createMcpModelPorts(
+          context,
+          args.collection,
+          dependencies.modelPortFactory,
+          { generation: true }
+        );
+        if (!modelPorts.genPort) {
+          throw new Error(
+            "Answer generation requested but no generation model is available"
+          );
+        }
+        const result = await buildVerifiedAsk(query, options, {
+          store: context.store,
+          config: context.config,
+          indexName: context.indexName,
+          vectorIndex: modelPorts.vectorIndex,
+          embedPort: modelPorts.embedPort,
+          rerankPort: modelPorts.rerankPort,
+          genPort: modelPorts.genPort,
+          traceSession,
+        });
+        const finished = await traceSession?.finish(
+          answerTraceTerminalStatus(result.citations)
+        );
+        if (finished && !finished.ok) throw new Error(finished.error.message);
+        return attachRetrievalTraceMetadata(result, traceSession);
+      } catch (error) {
+        await finishRetrievalTraceAfterError(traceSession, error);
+        throw error;
+      } finally {
+        await modelPorts?.dispose();
+      }
+    },
+    formatVerifiedAskReadable
+  );

package/src/mcp/tools/context.ts

@@ -2,7 +2,11 @@
 
 import type { RetrievalTraceSession } from "../../core/retrieval-trace-session";
 import type { ModelLease } from "../../llm/nodeLlamaCpp/lifecycle";
-import type { EmbeddingPort, RerankPort } from "../../llm/types";
+import type {
+  EmbeddingPort,
+  GenerationPort,
+  RerankPort,
+} from "../../llm/types";
 import type { VectorIndexPort } from "../../store/vector";
 import type { ToolContext } from "../server";
 import type { ToolResult } from "./index";
@@ -85,13 +89,15 @@ const runContextTool = async (
 
 interface McpModelPorts {
   embedPort: EmbeddingPort | null;
+  genPort: GenerationPort | null;
   rerankPort: RerankPort | null;
   vectorIndex: VectorIndexPort | null;
   dispose(): Promise<void>;
 }
 
-interface McpModelPortFactory {
+export interface McpModelPortFactory {
   createEmbeddingPort: LlmAdapter["createEmbeddingPort"];
+  createGenerationPort?: LlmAdapter["createGenerationPort"];
   createRerankPort: LlmAdapter["createRerankPort"];
   acquireModelLease?: LlmAdapter["acquireModelLease"];
 }
@@ -109,7 +115,8 @@ export const disposeContextModelOwners = async (
 export const createMcpModelPorts = async (
   context: ToolContext,
   collection?: string,
-  factoryOverride?: McpModelPortFactory
+  factoryOverride?: McpModelPortFactory,
+  options: { generation?: boolean } = {}
 ): Promise<McpModelPorts> => {
   const llm = new LlmAdapter(context.config);
   const factory = factoryOverride ?? llm;
@@ -125,6 +132,7 @@ export const createMcpModelPorts = async (
   let embedPort: EmbeddingPort | null = null;
   let ownedEmbedPort: EmbeddingPort | null = null;
   let rerankPort: RerankPort | null = null;
+  let genPort: GenerationPort | null = null;
   let vectorIndex: VectorIndexPort | null = null;
   try {
     const embedResult = await factory.createEmbeddingPort(embedUri, {
@@ -152,14 +160,26 @@ export const createMcpModelPorts = async (
       }
     );
     if (rerankResult.ok) rerankPort = rerankResult.value;
+    if (options.generation && factory.createGenerationPort) {
+      const genResult = await factory.createGenerationPort(
+        resolveModelUri(context.config, "gen", undefined, collection),
+        {
+          policy,
+          onProgress: (value) => progress("gen", value),
+        }
+      );
+      if (genResult.ok) genPort = genResult.value;
+    }
     return {
       embedPort,
+      genPort,
       rerankPort,
       vectorIndex,
       async dispose() {
         await disposeContextModelOwners(
-          [ownedEmbedPort, rerankPort].filter(
-            (port): port is EmbeddingPort | RerankPort => port !== null
+          [ownedEmbedPort, rerankPort, genPort].filter(
+            (port): port is EmbeddingPort | RerankPort | GenerationPort =>
+              port !== null
           ),
           lease
         );
@@ -167,8 +187,9 @@ export const createMcpModelPorts = async (
     };
   } catch (error) {
     await disposeContextModelOwners(
-      [ownedEmbedPort, rerankPort].filter(
-        (port): port is EmbeddingPort | RerankPort => port !== null
+      [ownedEmbedPort, rerankPort, genPort].filter(
+        (port): port is EmbeddingPort | RerankPort | GenerationPort =>
+          port !== null
       ),
       lease
     );

package/src/mcp/tools/index.ts

@@ -19,6 +19,7 @@ import { NOTE_PRESETS, type NotePresetId } from "../../core/note-presets";
 import { RETRIEVAL_TRACE_METADATA } from "../../core/retrieval-trace-session";
 import { normalizeTag } from "../../core/tags";
 import { handleAddCollection } from "./add-collection";
+import { askInputSchema, handleAsk } from "./ask";
 import { handleCapture } from "./capture";
 import { handleClearCollectionEmbeddings } from "./clear-collection-embeddings";
 import { handleContext, handleContextVerify } from "./context";
@@ -96,6 +97,7 @@ export const MCP_TOOL_DESCRIPTIONS = {
     "Compile one deterministic, budgeted, extractive evidence Capsule with exact line spans, coverage gaps, omissions, provenance, and verification fingerprints. Raw search/get tools remain available for manual retrieval.",
   contextVerify:
     "Verify a saved Context Capsule without rebuilding or mutating it. Reports unchanged, stale, missing, reranked, and fingerprint drift states against the active index.",
+  ask: "Generate one answer from a deterministic Context Capsule, verify every substantive claim against exact retained spans, and abstain unless support coverage is complete. Read-only; returns the Capsule, freshness receipt, claim verdicts, gaps, and evidence IDs.",
 } as const;
 
 /** Tool names whose execution mutates disk, config, or index state. */
@@ -978,6 +980,13 @@ export function registerTools(server: McpServer, ctx: ToolContext): void {
     (args) => handleContextVerify(args, ctx)
   );
 
+  server.tool(
+    "gno_ask",
+    MCP_TOOL_DESCRIPTIONS.ask,
+    askInputSchema.shape,
+    (args) => handleAsk(args, ctx)
+  );
+
   server.tool(
     "gno_search",
     MCP_TOOL_DESCRIPTIONS.search,

package/src/pipeline/claim-verification-schema.ts

@@ -0,0 +1,235 @@
+import { z } from "zod";
+
+export const CLAIM_VERIFICATION_SCHEMA_VERSION = "1.0" as const;
+export const CLAIM_COORDINATE_SPACE = "utf16_code_units" as const;
+
+const sha256Schema = z.string().regex(/^[a-f0-9]{64}$/);
+
+export const semanticClaimJudgmentSchema = z
+  .object({
+    claimId: sha256Schema,
+    verdict: z.enum(["supported", "contradicted"]),
+    confidence: z.number().min(0).max(1),
+    evidenceIds: z.array(sha256Schema).min(1).max(256),
+    rationaleCode: z.enum(["semantic_entailment", "semantic_contradiction"]),
+    verifierFingerprint: sha256Schema,
+  })
+  .strict()
+  .superRefine((value, context) => {
+    const expected =
+      value.verdict === "supported"
+        ? "semantic_entailment"
+        : "semantic_contradiction";
+    if (
+      value.rationaleCode !== expected ||
+      new Set(value.evidenceIds).size !== value.evidenceIds.length
+    ) {
+      context.addIssue({
+        code: "custom",
+        message: "semantic judgment is incoherent",
+      });
+    }
+  });
+
+export type SemanticClaimJudgment = z.infer<typeof semanticClaimJudgmentSchema>;
+const evidenceReferenceSchema = z
+  .object({
+    evidenceId: sha256Schema,
+    uri: z.string().min(1).max(2048).startsWith("gno://"),
+    startLine: z.number().int().positive(),
+    endLine: z.number().int().positive(),
+    text: z.string().min(1),
+    sourceHash: sha256Schema,
+    mirrorHash: sha256Schema,
+    passageHash: sha256Schema,
+  })
+  .strict()
+  .refine((value) => value.endLine >= value.startLine, {
+    message: "evidence line range is reversed",
+    path: ["endLine"],
+  });
+
+const rejectedCitationSchema = z
+  .object({
+    marker: z.string().min(1),
+    start: z.number().int().nonnegative(),
+    end: z.number().int().positive(),
+    evidenceId: sha256Schema.nullable(),
+    reason: z.enum([
+      "malformed_citation",
+      "out_of_capsule",
+      "freshness_unavailable",
+      "freshness_receipt_invalid",
+      "freshness_receipt_mismatch",
+      "evidence_stale",
+      "evidence_missing",
+      "orphan_citation",
+    ]),
+  })
+  .strict()
+  .refine((value) => value.end > value.start, {
+    message: "citation span must be non-empty",
+    path: ["end"],
+  });
+
+const verifiedClaimSchema = z
+  .object({
+    claimId: sha256Schema,
+    text: z.string().min(1),
+    start: z.number().int().nonnegative(),
+    end: z.number().int().positive(),
+    status: z.enum(["supported", "contradicted", "insufficient", "uncertain"]),
+    confidence: z.number().min(0).max(1).nullable(),
+    rationaleCode: z.enum([
+      "semantic_entailment",
+      "semantic_contradiction",
+      "no_valid_evidence",
+      "semantic_judgment_unavailable",
+    ]),
+    verifierFingerprint: sha256Schema.nullable(),
+    evidence: z.array(evidenceReferenceSchema).max(256),
+    rejectedCitations: z.array(rejectedCitationSchema).max(256),
+  })
+  .strict()
+  .superRefine((value, context) => {
+    if (value.end <= value.start) {
+      context.addIssue({
+        code: "custom",
+        message: "claim span must be non-empty",
+        path: ["end"],
+      });
+    }
+    const semantic =
+      value.status === "supported" || value.status === "contradicted";
+    const expectedRationale = {
+      supported: "semantic_entailment",
+      contradicted: "semantic_contradiction",
+      insufficient: "no_valid_evidence",
+      uncertain: "semantic_judgment_unavailable",
+    }[value.status];
+    const evidenceCountValid =
+      value.status === "insufficient"
+        ? value.evidence.length === 0
+        : value.evidence.length > 0;
+    if (
+      value.rationaleCode !== expectedRationale ||
+      !evidenceCountValid ||
+      (semantic &&
+        (value.confidence === null || value.verifierFingerprint === null)) ||
+      (!semantic &&
+        (value.confidence !== null || value.verifierFingerprint !== null))
+    ) {
+      context.addIssue({
+        code: "custom",
+        message: "claim status fields are incoherent",
+      });
+    }
+    const ids = value.evidence.map((item) => item.evidenceId);
+    if (new Set(ids).size !== ids.length) {
+      context.addIssue({
+        code: "custom",
+        message: "claim evidence must be unique",
+        path: ["evidence"],
+      });
+    }
+  });
+
+const coverageSchema = z
+  .object({
+    totalClaims: z.number().int().nonnegative(),
+    supportedClaims: z.number().int().nonnegative(),
+    contradictedClaims: z.number().int().nonnegative(),
+    insufficientClaims: z.number().int().nonnegative(),
+    uncertainClaims: z.number().int().nonnegative(),
+    supportedRatio: z.number().min(0).max(1),
+  })
+  .strict();
+
+export const claimVerificationResultSchema = z
+  .object({
+    schemaVersion: z.literal(CLAIM_VERIFICATION_SCHEMA_VERSION),
+    coordinateSpace: z.literal(CLAIM_COORDINATE_SPACE),
+    capsuleId: sha256Schema,
+    answerHash: sha256Schema,
+    coverageThreshold: z.literal(1),
+    claims: z.array(verifiedClaimSchema).max(256),
+    rejectedCitations: z.array(rejectedCitationSchema).max(256),
+    coverage: coverageSchema,
+    answerStatus: z.enum(["verified", "abstained"]),
+    abstained: z.boolean(),
+    abstentionReason: z
+      .enum([
+        "contradiction_detected",
+        "coverage_below_threshold",
+        "no_substantive_claims",
+        "citation_hygiene_failed",
+      ])
+      .nullable(),
+    abstentionText: z.string().min(1).nullable(),
+  })
+  .strict()
+  .superRefine((value, context) => {
+    const counts = {
+      supportedClaims: value.claims.filter(
+        (claim) => claim.status === "supported"
+      ).length,
+      contradictedClaims: value.claims.filter(
+        (claim) => claim.status === "contradicted"
+      ).length,
+      insufficientClaims: value.claims.filter(
+        (claim) => claim.status === "insufficient"
+      ).length,
+      uncertainClaims: value.claims.filter(
+        (claim) => claim.status === "uncertain"
+      ).length,
+    };
+    const supportedRatio =
+      value.claims.length === 0
+        ? 0
+        : counts.supportedClaims / value.claims.length;
+    const expectedReason =
+      value.claims.length === 0
+        ? "no_substantive_claims"
+        : counts.contradictedClaims > 0
+          ? "contradiction_detected"
+          : value.rejectedCitations.length > 0 ||
+              value.claims.some((claim) => claim.rejectedCitations.length > 0)
+            ? "citation_hygiene_failed"
+            : supportedRatio < 1
+              ? "coverage_below_threshold"
+              : null;
+    const coverageValid =
+      value.coverage.totalClaims === value.claims.length &&
+      Object.entries(counts).every(
+        ([key, count]) => value.coverage[key as keyof typeof counts] === count
+      ) &&
+      value.coverage.supportedRatio === supportedRatio;
+    const abstentionValid =
+      value.abstentionReason === expectedReason &&
+      value.abstained === (expectedReason !== null) &&
+      value.answerStatus ===
+        (expectedReason === null ? "verified" : "abstained") &&
+      (expectedReason === null
+        ? value.abstentionText === null
+        : value.abstentionText !== null);
+    const spansValid = value.claims.every(
+      (claim, index) =>
+        index === 0 || claim.start >= (value.claims[index - 1]?.end ?? 0)
+    );
+    const claimIds = value.claims.map((claim) => claim.claimId);
+    if (
+      !coverageValid ||
+      !abstentionValid ||
+      !spansValid ||
+      new Set(claimIds).size !== claimIds.length
+    ) {
+      context.addIssue({
+        code: "custom",
+        message: "claim verification aggregate is incoherent",
+      });
+    }
+  });
+
+export type ClaimVerificationResult = z.infer<
+  typeof claimVerificationResultSchema
+>;