@gmickel/gno 1.18.0 → 1.20.0

package/spec/output-schemas/tags-list.schema.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/tags-list@1.0",
+  "title": "GNO Tags List",
+  "description": "List of tags with document counts",
+  "type": "object",
+  "required": ["tags", "meta"],
+  "properties": {
+    "tags": {
+      "type": "array",
+      "description": "List of tags with counts",
+      "items": {
+        "type": "object",
+        "required": ["tag", "count"],
+        "properties": {
+          "tag": {
+            "type": "string",
+            "description": "Tag name (lowercase, alphanumeric with hyphens/dots/slashes)"
+          },
+          "count": {
+            "type": "integer",
+            "description": "Number of documents with this tag",
+            "minimum": 1
+          }
+        }
+      }
+    },
+    "meta": {
+      "type": "object",
+      "required": ["totalTags"],
+      "properties": {
+        "totalTags": {
+          "type": "integer",
+          "description": "Total number of unique tags",
+          "minimum": 0
+        },
+        "collection": {
+          "type": "string",
+          "description": "Collection filter applied"
+        },
+        "prefix": {
+          "type": "string",
+          "description": "Prefix filter applied"
+        }
+      }
+    }
+  }
+}

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

@@ -24,8 +24,9 @@ import { resolveModelUri } from "../llm/registry";
 const fingerprint = (value: unknown): string =>
   sha256Text(canonicalVerifierJson(value));
 
-const configFingerprint = (deps: ContextCapsuleRuntimeDeps): string =>
-  fingerprint(deps.config);
+export const contextRuntimeConfigFingerprint = (
+  deps: Pick<ContextCapsuleRuntimeDeps, "config">
+): string => fingerprint(deps.config);
 
 const configuredContextFingerprint = (
   deps: ContextCapsuleRuntimeDeps
@@ -75,7 +76,7 @@ const capsuleCapabilityStates = (
     ["embedding_unavailable"]
   ),
   reranking: capabilityState(
-    input.depthPolicy !== "fast",
+    input.depthPolicy !== "fast" && !input.noRerank,
     draft.retrieval.reranked,
     ["reranking_unavailable"]
   ),
@@ -191,10 +192,14 @@ export const projectContextCapsule = (
       request: {
         author: input.author,
         lang: input.lang,
+        intent: input.intent,
+        exclude: input.exclude,
+        minScore: input.minScore,
         queryModes: input.queryModes,
         limit: input.limit,
         candidateLimit: input.candidateLimit,
         graphRequested: input.graph,
+        rerankRequested: input.depthPolicy !== "fast" && !input.noRerank,
       },
       capabilityStates,
       indexSnapshot: {
@@ -221,7 +226,7 @@ export const projectContextCapsule = (
         : null,
     },
     fingerprints: {
-      config: configFingerprint(deps),
+      config: contextRuntimeConfigFingerprint(deps),
       retrieval: retrievalFingerprint(base, snapshots.contextFingerprint),
       embeddingModel: capabilities.semanticSearch
         ? sha256Text(deps.embedPort?.modelUri ?? "")
@@ -292,7 +297,7 @@ export const currentContextFingerprints = (
   capsule: ContextCapsuleV1,
   deps: ContextCapsuleRuntimeDeps
 ) => ({
-  config: configFingerprint(deps),
+  config: contextRuntimeConfigFingerprint(deps),
   retrieval: retrievalFingerprint(capsule, configuredContextFingerprint(deps)),
   embeddingModel: capsule.capabilities.semanticSearch
     ? sha256Text(

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

@@ -2,6 +2,7 @@ import type { Config } from "../config/types";
 import type { ContextCapsuleV1 } from "../core/context-capsule";
 import type { ContextEvidenceCompilerDeps } from "../core/context-evidence";
 import type { ContextVerifierDeps } from "../core/context-verifier";
+import type { RetrievalTraceSession } from "../core/retrieval-trace-session";
 import type { EmbeddingPort, RerankPort } from "../llm/types";
 import type { QueryModeInput } from "../pipeline/types";
 import type { StorePort } from "../store/types";
@@ -21,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;
@@ -45,6 +50,8 @@ export interface ContextCapsuleRuntimeDeps {
   countTokens?: (accountingJson: string) => number;
   tokenizerFingerprint?: string | null;
   resolveCurrentRanks?: ContextVerifierDeps["resolveCurrentRanks"];
+  /** Optional non-canonical receipt session owned by the calling surface. */
+  traceSession?: RetrievalTraceSession;
 }
 
 export type ContextRuntimeErrorCode =

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,
@@ -89,7 +93,11 @@ export const buildContextCapsule = async (
             rerankPort: requestNoRerank ? null : (deps.rerankPort ?? null),
           },
           request.query,
-          { ...request, noRerank: requestNoRerank }
+          {
+            ...request,
+            noRerank: requestNoRerank,
+            traceSession: deps.traceSession,
+          }
         );
         if (!result.ok) {
           throw new ContextRuntimeError(
@@ -115,6 +123,16 @@ export const buildContextCapsule = async (
         : "No in-scope evidence was available for the Context Capsule"
     );
   }
+  const traceResult = await deps.traceSession?.recordContext(
+    plan.projection.value
+  );
+  if (traceResult && !traceResult.ok) {
+    throw new ContextRuntimeError(
+      "retrieval_failed",
+      `Trace recording failed: ${traceResult.error.message}`,
+      traceResult.error.cause
+    );
+  }
   return plan.projection.value;
 };
 

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