@gmickel/gno 1.18.0 → 1.20.0

package/src/pipeline/answer.ts

@@ -5,6 +5,7 @@
  * @module src/pipeline/answer
  */
 
+import type { RetrievalTraceSession } from "../core/retrieval-trace-session";
 import type { GenerationPort } from "../llm/types";
 import type { StorePort } from "../store/types";
 import type {
@@ -15,6 +16,11 @@ import type {
 } from "./types";
 
 import { buildAnswerPrompt, type AnswerPromptSource } from "./answer-prompt";
+import { attachCitationTraceMetadata } from "./trace-metadata";
+import {
+  CITATION_TRACE_METADATA,
+  SEARCH_RESULT_PLANNER_METADATA,
+} from "./types";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Constants
@@ -24,6 +30,11 @@ import { buildAnswerPrompt, type AnswerPromptSource } from "./answer-prompt";
 export const ABSTENTION_MESSAGE =
   "I don't have enough information in the provided sources to answer this question.";
 
+export const answerTraceTerminalStatus = (
+  citations: readonly Citation[] | undefined
+): "completed" | "partial" =>
+  citations && citations.length > 0 ? "completed" : "partial";
+
 /** Max characters per document (~8K tokens) */
 const MAX_DOC_CHARS = 32_000;
 
@@ -86,6 +97,65 @@ interface SelectedSource {
   reason: string;
 }
 
+interface ExactAnswerPassage {
+  text: string;
+  startLine: number;
+  endLine: number;
+  passageHash: string;
+}
+
+const sha256 = (value: string): string =>
+  new Bun.CryptoHasher("sha256").update(value).digest("hex");
+
+const completeLinePrefix = (
+  content: string,
+  startLine: number,
+  maxChars: number
+): ExactAnswerPassage | null => {
+  const lines = content.split("\n");
+  if (lines.length === 0) return null;
+  const selected: string[] = [];
+  let characters = 0;
+  for (const line of lines) {
+    const addition = selected.length === 0 ? line.length : line.length + 1;
+    if (characters + addition > maxChars) break;
+    selected.push(line);
+    characters += addition;
+  }
+  if (selected.length === 0) return null;
+  const text = selected.join("\n");
+  if (!text.trim()) return null;
+  return {
+    text,
+    startLine,
+    endLine: startLine + selected.length - 1,
+    passageHash: sha256(text),
+  };
+};
+
+const anchoredCompleteLines = (
+  content: string,
+  metadata: SearchResult[typeof SEARCH_RESULT_PLANNER_METADATA]
+): ExactAnswerPassage | null => {
+  if (
+    !metadata?.passageHash ||
+    metadata.startLine === undefined ||
+    metadata.endLine === undefined ||
+    metadata.endLine < metadata.startLine
+  ) {
+    return null;
+  }
+  const lines = content.split("\n");
+  const text = lines.slice(metadata.startLine - 1, metadata.endLine).join("\n");
+  if (
+    text.split("\n").length !== metadata.endLine - metadata.startLine + 1 ||
+    sha256(text) !== metadata.passageHash
+  ) {
+    return null;
+  }
+  return completeLinePrefix(text, metadata.startLine, MAX_DOC_CHARS);
+};
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Citation Processing
 // ─────────────────────────────────────────────────────────────────────────────
@@ -423,53 +493,78 @@ export async function generateGroundedAnswer(
 ): Promise<AnswerGenerationResult | null> {
   const { genPort, store } = deps;
   const sourceSelection = selectAdaptiveSources(query, results);
+  const finalRanks = new Map(
+    results.map((result, index) => [result, index + 1] as const)
+  );
   const promptSources: AnswerPromptSource[] = [];
   const citations: Citation[] = [];
   let citationIndex = 0;
 
   for (const r of sourceSelection.selected) {
-    let content: string | null = null;
-    let usedFullContent = false;
+    let passage: ExactAnswerPassage | null = null;
+    const plannerMetadata = r[SEARCH_RESULT_PLANNER_METADATA];
+    const sourceHash = r.source.sourceHash;
+    const mirrorHash = r.conversion?.mirrorHash;
 
     // Try to fetch full document content if store available
-    if (store && r.conversion?.mirrorHash) {
-      const contentResult = await store.getContent(r.conversion.mirrorHash);
+    if (store && mirrorHash) {
+      const contentResult = await store.getContent(mirrorHash);
       if (contentResult.ok && contentResult.value) {
-        content = contentResult.value;
-        usedFullContent = true;
-        // Truncate to max doc chars
-        if (content.length > MAX_DOC_CHARS) {
-          content = `${content.slice(0, MAX_DOC_CHARS)}\n\n[... truncated ...]`;
+        if (sha256(contentResult.value) === mirrorHash) {
+          passage =
+            anchoredCompleteLines(contentResult.value, plannerMetadata) ??
+            completeLinePrefix(contentResult.value, 1, MAX_DOC_CHARS);
         }
       }
     }
 
-    // Fallback to snippet if full content unavailable
-    if (!content) {
-      if (!r.snippet || r.snippet.trim().length === 0) {
-        continue;
-      }
-      content =
-        r.snippet.length > MAX_SNIPPET_CHARS
-          ? `${r.snippet.slice(0, MAX_SNIPPET_CHARS)}...`
-          : r.snippet;
+    // Snippet fallback is allowed only when the planner proves it is the exact
+    // complete canonical chunk, never an FTS marker/ellipsis presentation.
+    if (
+      !passage &&
+      plannerMetadata?.passageHash &&
+      plannerMetadata.startLine !== undefined &&
+      plannerMetadata.endLine !== undefined &&
+      sha256(r.snippet) === plannerMetadata.passageHash &&
+      r.snippet.split("\n").length ===
+        plannerMetadata.endLine - plannerMetadata.startLine + 1
+    ) {
+      passage = completeLinePrefix(
+        r.snippet,
+        plannerMetadata.startLine,
+        MAX_SNIPPET_CHARS
+      );
     }
+    if (!(passage && sourceHash && mirrorHash)) continue;
 
     citationIndex += 1;
     promptSources.push({
       index: citationIndex,
       docid: r.docid,
       uri: r.uri,
-      content,
+      content: passage.text,
       guidance: r.context,
     });
-    // Clear line range when citing full content (not a specific snippet)
-    citations.push({
-      docid: r.docid,
-      uri: r.uri,
-      startLine: usedFullContent ? undefined : r.snippetRange?.startLine,
-      endLine: usedFullContent ? undefined : r.snippetRange?.endLine,
-    });
+    citations.push(
+      attachCitationTraceMetadata(
+        {
+          docid: r.docid,
+          uri: r.uri,
+          startLine: passage.startLine,
+          endLine: passage.endLine,
+        },
+        {
+          sourceHash,
+          mirrorHash,
+          passageHash: passage.passageHash,
+          seq: plannerMetadata?.seq,
+          rank: finalRanks.get(r) ?? 1,
+          plannerRank: plannerMetadata?.retrievalRank,
+          sources: plannerMetadata?.sources,
+          graphExpanded: plannerMetadata?.graphExpanded,
+        }
+      )
+    );
   }
 
   if (promptSources.length === 0) {
@@ -528,3 +623,49 @@ export function processAnswerResult(rawResult: AnswerGenerationResult): {
     answerContext: rawResult.answerContext,
   };
 }
+
+/** Process first, then record only citations retained in the final answer. */
+export async function processAnswerResultWithTrace(
+  rawResult: AnswerGenerationResult,
+  traceSession?: RetrievalTraceSession
+): Promise<ReturnType<typeof processAnswerResult>> {
+  const processed = processAnswerResult(rawResult);
+  if (!traceSession || processed.citations.length === 0) return processed;
+  const evidence = processed.citations.flatMap((citation) => {
+    const metadata = citation[CITATION_TRACE_METADATA];
+    if (
+      !metadata ||
+      citation.startLine === undefined ||
+      citation.endLine === undefined
+    ) {
+      return [];
+    }
+    return [
+      {
+        docid: citation.docid,
+        uri: citation.uri,
+        sourceHash: metadata.sourceHash,
+        mirrorHash: metadata.mirrorHash,
+        passageHash: metadata.passageHash,
+        startLine: citation.startLine,
+        endLine: citation.endLine,
+        rank: metadata.rank,
+        ...(metadata.seq === undefined ? {} : { seq: metadata.seq }),
+        ...(metadata.plannerRank === undefined
+          ? {}
+          : { plannerRank: metadata.plannerRank }),
+        ...(metadata.sources === undefined
+          ? {}
+          : { sources: metadata.sources }),
+        ...(metadata.graphExpanded === undefined
+          ? {}
+          : { graphExpanded: metadata.graphExpanded }),
+      },
+    ];
+  });
+  const recorded = await traceSession.recordEvidence("cite", evidence);
+  if (!recorded.ok) {
+    throw new Error(`Trace recording failed: ${recorded.error.message}`);
+  }
+  return processed;
+}

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
+>;