@gmickel/gno 1.19.0 → 1.21.0

package/src/app/context-runtime-input.ts

@@ -315,16 +315,40 @@ export const normalizeContextBuildInput = (
       "Context graph flag must be boolean"
     );
   }
+  if (input.noRerank !== undefined && typeof input.noRerank !== "boolean") {
+    throw new ContextRuntimeError(
+      "invalid_filter",
+      "Context noRerank flag must be boolean"
+    );
+  }
+  if (
+    input.minScore !== undefined &&
+    (typeof input.minScore !== "number" ||
+      !Number.isFinite(input.minScore) ||
+      input.minScore < 0 ||
+      input.minScore > 1)
+  ) {
+    throw new ContextRuntimeError(
+      "invalid_filter",
+      "Context minimum score must be between 0 and 1"
+    );
+  }
   const author =
     typeof input.author === "string"
       ? input.author.normalize("NFC").trim()
       : null;
   const lang =
     typeof input.lang === "string" ? input.lang.normalize("NFC").trim() : null;
+  const intent =
+    typeof input.intent === "string"
+      ? input.intent.normalize("NFC").trim()
+      : null;
   if (
     (input.author !== undefined &&
       (!author || author.length > MAX_FILTER_LENGTH)) ||
-    (input.lang !== undefined && (!lang || !isValidLanguageHint(lang)))
+    (input.lang !== undefined && (!lang || !isValidLanguageHint(lang))) ||
+    (input.intent !== undefined &&
+      (!intent || intent.length > MAX_TEXT_LENGTH || intent.includes("\r")))
   ) {
     throw new ContextRuntimeError(
       "invalid_filter",
@@ -344,9 +368,13 @@ export const normalizeContextBuildInput = (
     categories: canonicalFilters(input.categories, "categories"),
     author,
     lang,
+    intent,
+    exclude: canonicalFilters(input.exclude, "exclude"),
+    minScore: input.minScore ?? null,
     since: temporalRange.since,
     until: temporalRange.until,
     graph: input.graph ?? false,
+    noRerank: input.noRerank ?? false,
     limit,
     candidateLimit,
     budgetTokens,

package/src/app/context-runtime-types.ts

@@ -22,9 +22,13 @@ export interface ContextCapsuleBuildInput {
   categories?: string[];
   author?: string;
   lang?: string;
+  intent?: string;
+  exclude?: string[];
+  minScore?: number;
   since?: string;
   until?: string;
   graph?: boolean;
+  noRerank?: boolean;
   limit?: number;
   candidateLimit?: number;
   budgetTokens: number;

package/src/app/context-runtime.ts

@@ -48,7 +48,7 @@ export const buildContextCapsule = async (
     now,
     deps.config.collections.map((collection) => collection.name)
   );
-  const noRerank = normalized.depthPolicy === "fast";
+  const noRerank = normalized.depthPolicy === "fast" || normalized.noRerank;
   const plan = await compileContextEvidence<ContextCapsuleV1>(
     {
       goal: normalized.goal,
@@ -62,9 +62,13 @@ export const buildContextCapsule = async (
       categories: normalized.categories,
       author: normalized.author ?? undefined,
       lang: normalized.lang ?? undefined,
+      intent: normalized.intent ?? undefined,
+      exclude: normalized.exclude,
+      minScore: normalized.minScore ?? undefined,
       since: normalized.since,
       until: normalized.until,
       graph: normalized.graph,
+      noRerank: normalized.noRerank,
       limit: normalized.limit,
       candidateLimit: normalized.candidateLimit,
       temporalNow: now,

package/src/app/context-surface.ts

@@ -30,9 +30,13 @@ export const contextBuildSurfaceSchema = z
     categories: stringList.optional(),
     author: z.string().optional(),
     lang: z.string().optional(),
+    intent: z.string().optional(),
+    exclude: stringList.optional(),
+    minScore: z.number().min(0).max(1).optional(),
     since: z.string().optional(),
     until: z.string().optional(),
     graph: z.boolean().optional(),
+    noRerank: z.boolean().optional(),
     limit: positiveInteger.optional(),
     candidateLimit: positiveInteger.optional(),
     budgetTokens: positiveInteger,

package/src/app/verified-ask.ts

@@ -0,0 +1,291 @@
+/** Shared closed-evidence Ask synthesis boundary. */
+
+import type {
+  ContextCapsuleV1,
+  ContextCapsuleVerification,
+} from "../core/context-capsule";
+import type { RetrievalTraceSession } from "../core/retrieval-trace-session";
+import type { GenerationPort } from "../llm/types";
+import type { AskOptions, AskResult, Citation } from "../pipeline/types";
+import type { ContextCapsuleRuntimeDeps } from "./context-runtime";
+
+import { buildAnswerPrompt } from "../pipeline/answer-prompt";
+import { CLAIM_ABSTENTION_TEXT } from "../pipeline/claim-verification";
+import { verifyClaimsSemantically } from "../pipeline/claim-verifier";
+import { attachCitationTraceMetadata } from "../pipeline/trace-metadata";
+import { CITATION_TRACE_METADATA } from "../pipeline/types";
+import {
+  buildContextCapsule,
+  verifyContextCapsuleRuntime,
+} from "./context-runtime";
+import { contextRuntimeConfigFingerprint } from "./context-runtime-contract";
+
+const DEFAULT_CONTEXT_BUDGET_TOKENS = 12_000;
+const DEFAULT_MAX_ANSWER_TOKENS = 512;
+const DEFAULT_VERIFIED_ASK_LIMIT = 5;
+const NUMERIC_CITATION_PATTERN = /\[(\d+)\]/g;
+
+export interface VerifiedAskDeps extends ContextCapsuleRuntimeDeps {
+  genPort: GenerationPort;
+  traceSession?: RetrievalTraceSession;
+}
+
+const generationSources = (capsule: ContextCapsuleV1) => {
+  const guidanceById = new Map(
+    capsule.guidance.configuredContexts.map((item) => [
+      item.contextId,
+      item.text,
+    ])
+  );
+  return capsule.evidence.map((evidence, index) => ({
+    index: index + 1,
+    docid: evidence.docid,
+    uri: evidence.uri,
+    content: evidence.text,
+    guidance: evidence.contextIds
+      .flatMap((contextId) => {
+        const text = guidanceById.get(contextId);
+        return text ? [text] : [];
+      })
+      .join("\n"),
+  }));
+};
+
+/** Map model-facing numeric citations to immutable Capsule evidence IDs. */
+export const mapAnswerCitationsToEvidence = (
+  answer: string,
+  capsule: ContextCapsuleV1
+): string =>
+  answer
+    .replace(NUMERIC_CITATION_PATTERN, (_marker, rawIndex: string) => {
+      const evidence = capsule.evidence[Number(rawIndex) - 1];
+      return evidence ? `[evidence:${evidence.evidenceId}]` : "";
+    })
+    .replace(/ {2,}/g, " ")
+    .trim();
+
+const retainedCitations = (
+  capsule: ContextCapsuleV1,
+  evidenceIds: ReadonlySet<string>
+): Citation[] =>
+  capsule.evidence.flatMap((evidence) => {
+    if (!evidenceIds.has(evidence.evidenceId)) return [];
+    return [
+      attachCitationTraceMetadata(
+        {
+          evidenceId: evidence.evidenceId,
+          docid: evidence.docid,
+          uri: evidence.uri,
+          startLine: evidence.startLine,
+          endLine: evidence.endLine,
+        },
+        {
+          sourceHash: evidence.sourceHash,
+          mirrorHash: evidence.mirrorHash,
+          passageHash: evidence.passageHash,
+          rank: evidence.selectionRank,
+          plannerRank: evidence.retrievalRank,
+          ...(evidence.retrievalSources === undefined
+            ? {}
+            : { sources: evidence.retrievalSources }),
+          ...(evidence.graphExpanded === undefined
+            ? {}
+            : { graphExpanded: evidence.graphExpanded }),
+        }
+      ),
+    ];
+  });
+
+const recordRetainedCitations = async (
+  traceSession: RetrievalTraceSession | undefined,
+  citations: readonly Citation[]
+): Promise<void> => {
+  if (!traceSession || citations.length === 0) return;
+  const evidence = 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.plannerRank === undefined
+          ? {}
+          : { plannerRank: metadata.plannerRank }),
+        ...(metadata.sources === undefined
+          ? {}
+          : { sources: metadata.sources }),
+        ...(metadata.graphExpanded === undefined
+          ? {}
+          : { graphExpanded: metadata.graphExpanded }),
+      },
+    ];
+  });
+  if (evidence.length === 0) return;
+  const recorded = await traceSession.recordEvidence("cite", evidence);
+  if (!recorded.ok) {
+    throw new Error(`Trace recording failed: ${recorded.error.message}`);
+  }
+};
+
+const citationEvidenceIds = (
+  verification: Awaited<ReturnType<typeof verifyClaimsSemantically>>,
+  statuses: ReadonlySet<"supported" | "contradicted">
+): Set<string> =>
+  new Set(
+    verification.verification.claims.flatMap((claim) =>
+      statuses.has(claim.status as "supported" | "contradicted")
+        ? claim.evidence.map((evidence) => evidence.evidenceId)
+        : []
+    )
+  );
+
+const recordCapability = async (
+  traceSession: RetrievalTraceSession | undefined,
+  capability: string,
+  status: "attempted" | "used" | "unavailable" | "failed",
+  reasonCode?: string
+): Promise<void> => {
+  const recorded = await traceSession?.recordCapability(
+    capability,
+    status,
+    reasonCode
+  );
+  if (recorded && !recorded.ok) {
+    throw new Error(`Trace recording failed: ${recorded.error.message}`);
+  }
+};
+
+export const buildVerifiedAsk = async (
+  query: string,
+  options: AskOptions,
+  deps: VerifiedAskDeps
+): Promise<AskResult> => {
+  const collection = options.collection;
+  const capsule = await buildContextCapsule(
+    {
+      goal: query,
+      query,
+      indexName: deps.indexName,
+      collections: collection ? [collection] : [],
+      queryModes: options.queryModes,
+      tagsAll: options.tagsAll,
+      tagsAny: options.tagsAny,
+      categories: options.categories,
+      author: options.author,
+      lang: options.lang,
+      intent: options.intent,
+      exclude: options.exclude,
+      minScore: options.minScore,
+      since: options.since,
+      until: options.until,
+      graph: Boolean(options.graph && !options.noGraph),
+      noRerank: options.noRerank,
+      limit: options.limit ?? DEFAULT_VERIFIED_ASK_LIMIT,
+      candidateLimit: options.candidateLimit,
+      budgetTokens:
+        options.contextBudgetTokens ?? DEFAULT_CONTEXT_BUDGET_TOKENS,
+      budgetBytes: options.contextBudgetBytes,
+      depthPolicy: "balanced",
+    },
+    deps
+  );
+  const freshness = await verifyContextCapsuleRuntime(capsule, deps);
+  return synthesizeVerifiedAsk(query, options, capsule, freshness, deps);
+};
+
+export const synthesizeVerifiedAsk = async (
+  query: string,
+  options: AskOptions,
+  capsule: ContextCapsuleV1,
+  freshness: ContextCapsuleVerification,
+  deps: Pick<
+    VerifiedAskDeps,
+    "config" | "genPort" | "indexName" | "traceSession"
+  >
+): Promise<AskResult> => {
+  await recordCapability(deps.traceSession, "answer_generation", "attempted");
+  const generated = await deps.genPort.generate(
+    buildAnswerPrompt(query, generationSources(capsule)),
+    {
+      temperature: 0,
+      maxTokens: options.maxAnswerTokens ?? DEFAULT_MAX_ANSWER_TOKENS,
+    }
+  );
+  await recordCapability(
+    deps.traceSession,
+    "answer_generation",
+    generated.ok ? "used" : "failed",
+    generated.ok ? undefined : "generation_failed"
+  );
+  const draftAnswer = generated.ok
+    ? mapAnswerCitationsToEvidence(generated.value, capsule)
+    : CLAIM_ABSTENTION_TEXT;
+  const verification = await verifyClaimsSemantically({
+    answer: draftAnswer,
+    capsule,
+    freshness,
+    genPort: generated.ok ? deps.genPort : null,
+    configFingerprint: contextRuntimeConfigFingerprint(deps),
+  });
+  await recordCapability(
+    deps.traceSession,
+    "claim_verification",
+    verification.semanticVerification.status === "completed"
+      ? "used"
+      : verification.semanticVerification.status,
+    verification.semanticVerification.reason
+  );
+  const citations = verification.verification.abstained
+    ? []
+    : retainedCitations(
+        capsule,
+        citationEvidenceIds(verification, new Set(["supported"]))
+      );
+  const traceCitations = retainedCitations(
+    capsule,
+    citationEvidenceIds(verification, new Set(["supported", "contradicted"]))
+  );
+  await recordRetainedCitations(deps.traceSession, traceCitations);
+  return {
+    query,
+    mode: capsule.capabilities.semanticSearch ? "hybrid" : "bm25_only",
+    queryLanguage: capsule.retrieval.request.lang ?? "und",
+    answer: verification.verification.abstained
+      ? (verification.verification.abstentionText ?? CLAIM_ABSTENTION_TEXT)
+      : draftAnswer,
+    citations,
+    results: [],
+    meta: {
+      expanded: false,
+      reranked: capsule.capabilities.reranking,
+      vectorsUsed: capsule.capabilities.semanticSearch,
+      intent: capsule.retrieval.request.intent ?? undefined,
+      candidateLimit: capsule.retrieval.request.candidateLimit,
+      exclude: capsule.retrieval.request.exclude,
+      answerGenerated: generated.ok,
+      totalResults: capsule.evidence.length,
+      verificationRequested: true,
+      abstained: verification.verification.abstained,
+    },
+    verification: {
+      schemaVersion: "1.0",
+      mode: "closed_capsule",
+      capsule,
+      freshness,
+      claims: verification.verification,
+      semantic: verification.semanticVerification,
+    },
+  };
+};

package/src/cli/commands/ask-format.ts

@@ -0,0 +1,255 @@
+import type { AskResult } from "../../pipeline/types";
+import type { AskCommandOptions, AskCommandResult } from "./ask";
+
+interface FormatOptions {
+  showSources?: boolean;
+}
+
+const exactSpan = (uri: string, startLine: number, endLine: number): string =>
+  `${uri}:L${startLine}${startLine === endLine ? "" : `-L${endLine}`}`;
+
+const replaceEvidenceMarkers = (value: string, data: AskResult): string => {
+  const citationNumbers = new Map(
+    (data.citations ?? []).flatMap((citation, index) =>
+      citation.evidenceId ? [[citation.evidenceId, index + 1] as const] : []
+    )
+  );
+  return value.replace(
+    /\[evidence:([a-f0-9]{64})\]/g,
+    (marker, evidenceId: string) => {
+      const citationNumber = citationNumbers.get(evidenceId);
+      return citationNumber === undefined ? marker : `[${citationNumber}]`;
+    }
+  );
+};
+
+const readableAnswer = (data: AskResult): string | undefined =>
+  data.answer ? replaceEvidenceMarkers(data.answer, data) : undefined;
+
+const capsuleEvidence = (data: AskResult) =>
+  data.verification?.capsule.evidence ?? [];
+
+const terminalVerification = (
+  verification: NonNullable<AskResult["verification"]>
+): string[] => {
+  const { claims, capsule, semantic } = verification;
+  const lines = [
+    "Verification:",
+    `  Answer status: ${claims.answerStatus}`,
+    `  Coverage: ${claims.coverage.supportedClaims}/${claims.coverage.totalClaims} supported (${(claims.coverage.supportedRatio * 100).toFixed(0)}%)`,
+    `  Semantic verifier: ${semantic.status} (${semantic.reason})`,
+  ];
+  if (claims.abstentionReason) {
+    lines.push(`  Abstention: ${claims.abstentionReason}`);
+  }
+  for (const [index, claim] of claims.claims.entries()) {
+    lines.push(`  Claim ${index + 1} [${claim.status}]: ${claim.text}`);
+    for (const evidence of claim.evidence) {
+      lines.push(
+        `    Evidence: ${exactSpan(evidence.uri, evidence.startLine, evidence.endLine)}`
+      );
+    }
+  }
+  const degraded = Object.entries(capsule.retrieval.capabilityStates).filter(
+    ([, state]) => state.requested && state.outcome !== "used"
+  );
+  for (const [name, state] of degraded) {
+    const reasons =
+      state.fallbackReasons.length > 0
+        ? ` (${state.fallbackReasons.join(", ")})`
+        : "";
+    lines.push(`  Capability: ${name} ${state.outcome}${reasons}`);
+  }
+  for (const facet of capsule.coverage.unresolvedFacets) {
+    lines.push(`  Gap: unresolved facet ${facet}`);
+  }
+  for (const gap of capsule.coverage.gaps) {
+    lines.push(`  Gap: ${gap.facet} (${gap.code})`);
+  }
+  lines.push("");
+  return lines;
+};
+
+const markdownVerification = (
+  verification: NonNullable<AskResult["verification"]>
+): string[] => {
+  const { claims, capsule, semantic } = verification;
+  const lines = [
+    "## Verification",
+    "",
+    `- Answer status: **${claims.answerStatus}**`,
+    `- Coverage: **${claims.coverage.supportedClaims}/${claims.coverage.totalClaims}** supported (${(claims.coverage.supportedRatio * 100).toFixed(0)}%)`,
+    `- Semantic verifier: **${semantic.status}** (\`${semantic.reason}\`)`,
+  ];
+  if (claims.abstentionReason) {
+    lines.push(`- Abstention: \`${claims.abstentionReason}\``);
+  }
+  lines.push("");
+  for (const [index, claim] of claims.claims.entries()) {
+    lines.push(`### Claim ${index + 1}: ${claim.status}`);
+    lines.push("");
+    lines.push(claim.text);
+    lines.push("");
+    for (const evidence of claim.evidence) {
+      lines.push(
+        `- Evidence: \`${exactSpan(evidence.uri, evidence.startLine, evidence.endLine)}\``
+      );
+    }
+    if (claim.evidence.length === 0) {
+      lines.push("- Evidence: none retained");
+    }
+    lines.push("");
+  }
+  const degraded = Object.entries(capsule.retrieval.capabilityStates).filter(
+    ([, state]) => state.requested && state.outcome !== "used"
+  );
+  if (
+    degraded.length > 0 ||
+    capsule.coverage.unresolvedFacets.length > 0 ||
+    capsule.coverage.gaps.length > 0
+  ) {
+    lines.push("### Gaps and degradation");
+    lines.push("");
+    for (const [name, state] of degraded) {
+      const reasons =
+        state.fallbackReasons.length > 0
+          ? `: ${state.fallbackReasons.join(", ")}`
+          : "";
+      lines.push(`- Capability \`${name}\`: ${state.outcome}${reasons}`);
+    }
+    for (const facet of capsule.coverage.unresolvedFacets) {
+      lines.push(`- Unresolved facet: ${facet}`);
+    }
+    for (const gap of capsule.coverage.gaps) {
+      lines.push(`- Gap: ${gap.facet} (\`${gap.code}\`)`);
+    }
+    lines.push("");
+  }
+  return lines;
+};
+
+const formatTerminal = (data: AskResult, opts: FormatOptions = {}): string => {
+  const lines: string[] = [];
+  const hasAnswer = Boolean(data.answer);
+  const answer = readableAnswer(data);
+  if (answer) {
+    lines.push("Answer:", answer, "");
+  }
+  if (data.verification) {
+    lines.push(...terminalVerification(data.verification));
+  }
+  if (data.citations && data.citations.length > 0) {
+    lines.push("Cited Sources:");
+    for (const [index, citation] of data.citations.entries()) {
+      const range =
+        citation.startLine === undefined
+          ? ""
+          : `:L${citation.startLine}${citation.endLine === undefined || citation.endLine === citation.startLine ? "" : `-L${citation.endLine}`}`;
+      lines.push(`  [${index + 1}] ${citation.uri}${range}`);
+    }
+    lines.push("");
+  }
+  const showAllSources = !hasAnswer || opts.showSources;
+  const verifiedEvidence = capsuleEvidence(data);
+  if (showAllSources && verifiedEvidence.length > 0) {
+    lines.push("All Capsule Evidence:");
+    for (const evidence of verifiedEvidence) {
+      lines.push(
+        `  [${evidence.docid}] ${exactSpan(evidence.uri, evidence.startLine, evidence.endLine)}`
+      );
+      if (evidence.title) lines.push(`    ${evidence.title}`);
+    }
+  } else if (showAllSources && data.results.length > 0) {
+    lines.push(hasAnswer ? "All Retrieved Sources:" : "Sources:");
+    for (const result of data.results) {
+      lines.push(`  [${result.docid}] ${result.uri}`);
+      if (result.title) lines.push(`    ${result.title}`);
+    }
+  } else if (hasAnswer && data.results.length > 0) {
+    const citedCount = data.citations?.length ?? 0;
+    if (data.results.length > citedCount) {
+      lines.push(
+        `(${data.results.length} sources retrieved, use --show-sources to list all)`
+      );
+    }
+  }
+  if (!data.answer && data.results.length === 0) {
+    lines.push("No relevant sources found.");
+  }
+  return replaceEvidenceMarkers(lines.join("\n"), data);
+};
+
+const formatMarkdown = (data: AskResult, opts: FormatOptions = {}): string => {
+  const lines: string[] = [`# Question: ${data.query}`, ""];
+  const hasAnswer = Boolean(data.answer);
+  const answer = readableAnswer(data);
+  if (answer) {
+    lines.push("## Answer", "", answer, "");
+  }
+  if (data.verification) {
+    lines.push(...markdownVerification(data.verification));
+  }
+  if (data.citations && data.citations.length > 0) {
+    lines.push("## Cited Sources", "");
+    for (const [index, citation] of data.citations.entries()) {
+      const range =
+        citation.startLine === undefined
+          ? ""
+          : `:L${citation.startLine}${citation.endLine === undefined || citation.endLine === citation.startLine ? "" : `-L${citation.endLine}`}`;
+      lines.push(`**[${index + 1}]** \`${citation.uri}${range}\``);
+    }
+    lines.push("");
+  }
+  if (!hasAnswer || opts.showSources) {
+    const verifiedEvidence = capsuleEvidence(data);
+    lines.push(
+      verifiedEvidence.length > 0
+        ? "## All Capsule Evidence"
+        : hasAnswer
+          ? "## All Retrieved Sources"
+          : "## Sources",
+      ""
+    );
+    if (verifiedEvidence.length > 0) {
+      for (const [index, evidence] of verifiedEvidence.entries()) {
+        lines.push(
+          `${index + 1}. **${evidence.title || evidence.uri}**`,
+          `   - URI: \`${exactSpan(evidence.uri, evidence.startLine, evidence.endLine)}\``
+        );
+      }
+    } else {
+      for (const [index, result] of data.results.entries()) {
+        lines.push(
+          `${index + 1}. **${result.title || result.source.relPath}**`
+        );
+        lines.push(`   - URI: \`${result.uri}\``);
+        lines.push(`   - Score: ${result.score.toFixed(2)}`);
+      }
+      if (data.results.length === 0) lines.push("*No relevant sources found.*");
+    }
+  }
+  lines.push(
+    "",
+    "---",
+    `*Mode: ${data.mode} | Expanded: ${data.meta.expanded} | Reranked: ${data.meta.reranked}*`
+  );
+  return replaceEvidenceMarkers(lines.join("\n"), data);
+};
+
+export function formatAsk(
+  result: AskCommandResult,
+  options: AskCommandOptions
+): string {
+  if (!result.success) {
+    return options.json
+      ? JSON.stringify({
+          error: { code: "ASK_FAILED", message: result.error },
+        })
+      : `Error: ${result.error}`;
+  }
+  if (options.json) return JSON.stringify(result.data, null, 2);
+  const formatOptions = { showSources: options.showSources };
+  return options.md
+    ? formatMarkdown(result.data, formatOptions)
+    : formatTerminal(result.data, formatOptions);
+}