@gmickel/gno 1.18.0 → 1.20.0

package/src/core/context-capsule-schema.ts

@@ -29,6 +29,14 @@ const positiveIntegerSchema = z.number().int().positive();
 const nonNegativeIntegerSchema = z.number().int().nonnegative();
 const COLLECTION_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/;
 const collectionSchema = nonEmptyTextSchema.max(64).regex(COLLECTION_PATTERN);
+const retrievalSourceSchema = z.enum([
+  "bm25",
+  "vector",
+  "bm25_variant",
+  "vector_variant",
+  "hyde",
+  "graph",
+]);
 const compareCodeUnits = (left: string, right: string): number =>
   left < right ? -1 : left > right ? 1 : 0;
 
@@ -244,6 +252,15 @@ export const contextCapsuleEvidenceSchema = z
     contextIds: z.array(sha256Schema).max(128),
     retrievalRank: positiveIntegerSchema,
     selectionRank: positiveIntegerSchema,
+    retrievalSources: z
+      .array(retrievalSourceSchema)
+      .min(1)
+      .max(6)
+      .refine((sources) => new Set(sources).size === sources.length, {
+        message: "retrievalSources must be unique",
+      })
+      .optional(),
+    graphExpanded: z.boolean().optional(),
     facets: z.array(nonEmptyTextSchema.max(512)).max(128),
     trust: z.literal("untrusted"),
     egress: z.enum([

package/src/core/context-capsule-validation.ts

@@ -352,11 +352,12 @@ export const validateContextCapsulePayload = (
     });
   }
   const semanticRequested = value.retrieval.depthPolicy !== "fast";
+  const rerankRequested =
+    value.retrieval.request.rerankRequested ?? semanticRequested;
   if (
     value.retrieval.capabilityStates.semanticSearch.requested !==
       semanticRequested ||
-    value.retrieval.capabilityStates.reranking.requested !==
-      semanticRequested ||
+    value.retrieval.capabilityStates.reranking.requested !== rerankRequested ||
     value.retrieval.capabilityStates.graphExpansion.requested !==
       value.retrieval.request.graphRequested
   ) {

package/src/core/context-capsule.ts

@@ -84,6 +84,17 @@ const normalizePayload = (
         value.retrieval.request.lang === null
           ? null
           : normalizeText(value.retrieval.request.lang),
+      ...(value.retrieval.request.intent === undefined
+        ? {}
+        : {
+            intent:
+              value.retrieval.request.intent === null
+                ? null
+                : normalizeText(value.retrieval.request.intent),
+          }),
+      ...(value.retrieval.request.exclude === undefined
+        ? {}
+        : { exclude: normalizeSet(value.retrieval.request.exclude) }),
       queryModes: value.retrieval.request.queryModes.map((mode) => ({
         ...mode,
         text: normalizeText(mode.text),
@@ -110,6 +121,13 @@ const normalizePayload = (
     documentDate: normalizeDocumentDate(item.documentDate),
     observedAt: normalizeDate(item.observedAt),
     contextIds: normalizeSet(item.contextIds),
+    ...(item.retrievalSources === undefined
+      ? {}
+      : {
+          retrievalSources: [...new Set(item.retrievalSources)].sort(
+            compareCodeUnits
+          ),
+        }),
     facets: normalizeSet(item.facets),
   })),
   guidance: {

package/src/core/context-compiler.ts

@@ -29,6 +29,7 @@ import type { ContextConfiguredGuidance } from "./context-guidance";
 import { decorateUriForIndex } from "../app/constants";
 import { canonicalizeIndexName } from "../app/index-name";
 import { resolveTemporalRange } from "../pipeline/temporal";
+import { attachSearchResultPlannerMetadata } from "../pipeline/trace-metadata";
 import {
   SEARCH_RESULT_PLANNER_METADATA,
   type SearchResultPlannerMetadata,
@@ -63,8 +64,8 @@ export interface ContextRetrievalRequest extends HybridSearchOptions {
 export interface ContextRetrievalCandidate {
   result: SearchResult;
   retrievalRank: number;
-  retrievalSources: FusionSource[];
-  graphExpanded: boolean;
+  retrievalSources?: FusionSource[];
+  graphExpanded?: boolean;
   contextIds: string[];
   observedAt: string | null;
 }
@@ -96,9 +97,13 @@ export interface ContextCompilerInput {
   categories?: string[];
   author?: string;
   lang?: string;
+  intent?: string;
+  exclude?: string[];
+  minScore?: number;
   since?: string;
   until?: string;
   graph?: boolean;
+  noRerank?: boolean;
   limit?: number;
   candidateLimit?: number;
   /** Frozen once by the caller; never defaulted from wall-clock time. */
@@ -163,16 +168,9 @@ const compareCodeUnits = (left: string, right: string): number => {
 };
 
 const plannerMeta = (
-  result: SearchResult,
-  fallbackRank: number
-): SearchResultPlannerMetadata =>
-  result[SEARCH_RESULT_PLANNER_METADATA] ?? {
-    retrievalRank: fallbackRank,
-    mirrorHash: result.conversion?.mirrorHash ?? "",
-    seq: 0,
-    sources: [],
-    graphExpanded: false,
-  };
+  result: SearchResult
+): SearchResultPlannerMetadata | undefined =>
+  result[SEARCH_RESULT_PLANNER_METADATA];
 
 const compareSearchResults = (
   left: SearchResult,
@@ -218,7 +216,9 @@ const referenceFromResult = (
 const normalizeMaterialized = <T>(
   draft: ContextMaterializedDraft<T>,
   facets: string[],
-  retrievalRank: number
+  retrievalRank: number,
+  retrievalSources: FusionSource[] | undefined,
+  graphExpanded: boolean | undefined
 ): MaterializedContextCandidate<T> => {
   const text = draft.text;
   if (
@@ -249,6 +249,10 @@ const normalizeMaterialized = <T>(
     text,
     facets,
     retrievalRank,
+    ...(retrievalSources === undefined
+      ? {}
+      : { retrievalSources: [...retrievalSources].sort(compareCodeUnits) }),
+    ...(graphExpanded === undefined ? {} : { graphExpanded }),
     value: draft.value,
   };
 };
@@ -351,10 +355,13 @@ export const planContextEvidence = async <T, P>(
         categories: input.categories,
         author: input.author,
         lang: input.lang,
+        intent: input.intent,
+        exclude: input.exclude,
+        minScore: input.minScore,
         since: temporalRange.since,
         until: temporalRange.until,
         graph: hasRerankBudget ? input.graph : false,
-        noRerank: hasRerankBudget ? undefined : true,
+        noRerank: input.noRerank || !hasRerankBudget ? true : undefined,
         limit: resultLimit === undefined ? undefined : Math.max(1, resultLimit),
         candidateLimit:
           rerankLimit === undefined ? undefined : Math.max(1, rerankLimit),
@@ -363,14 +370,20 @@ export const planContextEvidence = async <T, P>(
   }
   const decoratedResults = responses
     .flatMap((response) => response.results)
-    .map((result) => ({
-      ...result,
-      uri: decorateUriForIndex(result.uri, indexName),
-    }));
+    .map((result) => {
+      const decorated = {
+        ...result,
+        uri: decorateUriForIndex(result.uri, indexName),
+      };
+      const metadata = result[SEARCH_RESULT_PLANNER_METADATA];
+      return metadata
+        ? attachSearchResultPlannerMetadata(decorated, metadata)
+        : decorated;
+    });
   const results = decoratedResults
     .map((result, index) => ({
       result,
-      retrievalRank: plannerMeta(result, index + 1).retrievalRank,
+      retrievalRank: plannerMeta(result)?.retrievalRank ?? index + 1,
     }))
     .sort(
       (left, right) =>
@@ -400,8 +413,8 @@ export const planContextEvidence = async <T, P>(
   const referencesByCandidate: ContextCandidateReference[] = [];
 
   for (const [index, result] of results.entries()) {
-    const meta = plannerMeta(result, index + 1);
-    for (const source of meta.sources) retrievalSources.add(source);
+    const meta = plannerMeta(result);
+    for (const source of meta?.sources ?? []) retrievalSources.add(source);
     const retrievalReference = referenceFromResult(result);
     if (!isContextUriInScope(result.uri, indexName, collections, uriPrefix)) {
       for (const facet of facetPlan) {
@@ -424,9 +437,13 @@ export const planContextEvidence = async <T, P>(
     }
     plannedCandidates.push({
       result,
-      retrievalRank: meta.retrievalRank,
-      retrievalSources: [...meta.sources].sort(compareCodeUnits),
-      graphExpanded: meta.graphExpanded,
+      retrievalRank: meta?.retrievalRank ?? index + 1,
+      ...(meta === undefined
+        ? {}
+        : {
+            retrievalSources: [...meta.sources].sort(compareCodeUnits),
+            graphExpanded: meta.graphExpanded,
+          }),
       contextIds:
         guidance.idsByResultIdentity.get(
           contextGuidanceResultIdentity(result)
@@ -479,7 +496,9 @@ export const planContextEvidence = async <T, P>(
       normalizeMaterialized(
         outcome.candidate,
         matchedFacets,
-        plannedCandidate.retrievalRank
+        plannedCandidate.retrievalRank,
+        plannedCandidate.retrievalSources,
+        plannedCandidate.graphExpanded
       )
     );
   }

package/src/core/context-evidence.ts

@@ -490,6 +490,12 @@ export const toContextCapsuleEvidence = (
     text: candidate.text,
     retrievalRank: candidate.retrievalRank,
     selectionRank,
+    ...(candidate.retrievalSources === undefined
+      ? {}
+      : { retrievalSources: [...candidate.retrievalSources] }),
+    ...(candidate.graphExpanded === undefined
+      ? {}
+      : { graphExpanded: candidate.graphExpanded }),
     facets: [...candidate.facets],
   };
 };

package/src/core/retrieval-qrels.ts

@@ -0,0 +1,405 @@
+/** Canonical qrels artifacts derived only from persisted retrieval receipts. */
+
+import type {
+  RetrievalTraceBundle,
+  RetrievalTraceFingerprints,
+  RetrievalTraceJudgmentLabel,
+  RetrievalTraceTerminalStatus,
+  StoreResult,
+} from "../store/types";
+import type { EvidenceTarget } from "./retrieval-trace-management-helpers";
+
+import { hashTraceCanonical } from "../store/retrieval-trace-codec";
+import { err, ok } from "../store/types";
+import { parseRetrievalTraceFilters } from "./retrieval-trace-filters";
+import { stableTarget, targetKey } from "./retrieval-trace-management-helpers";
+
+export interface RetrievalQrelsEvidence {
+  docid: string;
+  sourceHash: string;
+  mirrorHash: string;
+  uri: string;
+  seq: number | null;
+  startLine: number;
+  endLine: number;
+  passageHash: string;
+  rank: number | null;
+  plannerRank: number | null;
+  score: number | null;
+  sources: string[];
+  graphExpanded: boolean;
+}
+
+export interface RetrievalQrel {
+  qrelId: string;
+  judgmentId: string;
+  label: RetrievalTraceJudgmentLabel;
+  relevance: 0 | 1;
+  baselineMissing: boolean;
+  target: EvidenceTarget;
+  evidence: RetrievalQrelsEvidence | null;
+}
+
+export interface RetrievalQrelsCase {
+  caseId: string;
+  traceId: string;
+  retrievalRunId: string;
+  terminalStatus: RetrievalTraceTerminalStatus;
+  query: {
+    text: string;
+    digest: string;
+    goalText: string | null;
+    goalDigest: string | null;
+    filters: Record<string, unknown>;
+  };
+  fingerprints: RetrievalTraceFingerprints;
+  baseline: {
+    ranked: RetrievalQrelsEvidence[];
+    capabilities: string[];
+    capabilityOutcomes: Array<{
+      capability: string;
+      status: "attempted" | "used" | "unavailable" | "failed";
+      reasonCode: string | null;
+    }>;
+    fallbackCodes: string[];
+    outcomes: {
+      opened: RetrievalQrelsEvidence[];
+      cited: RetrievalQrelsEvidence[];
+      pinned: RetrievalQrelsEvidence[];
+    };
+  };
+  judgments: {
+    history: Array<{
+      judgmentId: string;
+      label: RetrievalTraceJudgmentLabel;
+      targetKind: string;
+      target: EvidenceTarget;
+      createdAtMs: number;
+      canonicalDigest: string;
+    }>;
+    effective: string[];
+  };
+  qrels: RetrievalQrel[];
+}
+
+export interface RetrievalTraceQrelsArtifact {
+  schemaVersion: "1.0";
+  format: "qrels";
+  cases: RetrievalQrelsCase[];
+}
+
+const exactEvidence = (value: unknown): RetrievalQrelsEvidence | null => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const item = value as Record<string, unknown>;
+  if (
+    typeof item.docid !== "string" ||
+    typeof item.sourceHash !== "string" ||
+    typeof item.mirrorHash !== "string" ||
+    typeof item.uri !== "string" ||
+    !item.uri.startsWith("gno://") ||
+    typeof item.startLine !== "number" ||
+    typeof item.endLine !== "number" ||
+    typeof item.passageHash !== "string"
+  ) {
+    return null;
+  }
+  return {
+    docid: item.docid,
+    sourceHash: item.sourceHash,
+    mirrorHash: item.mirrorHash,
+    uri: item.uri,
+    seq: typeof item.seq === "number" ? item.seq : null,
+    startLine: item.startLine,
+    endLine: item.endLine,
+    passageHash: item.passageHash,
+    rank: typeof item.rank === "number" ? item.rank : null,
+    plannerRank: typeof item.plannerRank === "number" ? item.plannerRank : null,
+    score: typeof item.score === "number" ? item.score : null,
+    sources: Array.isArray(item.sources)
+      ? item.sources
+          .filter((entry): entry is string => typeof entry === "string")
+          .sort()
+      : [],
+    graphExpanded: item.graphExpanded === true,
+  };
+};
+
+const evidenceArray = (
+  payload: Record<string, unknown>,
+  key: "ranked" | "evidence"
+): RetrievalQrelsEvidence[] =>
+  Array.isArray(payload[key])
+    ? payload[key].flatMap((value) => {
+        const parsed = exactEvidence(value);
+        return parsed ? [parsed] : [];
+      })
+    : [];
+
+const sameDocument = (
+  target: EvidenceTarget,
+  evidence: RetrievalQrelsEvidence
+): boolean =>
+  (target.sourceHash !== undefined &&
+    target.sourceHash === evidence.sourceHash) ||
+  (target.docid !== undefined && target.docid === evidence.docid) ||
+  (target.uri !== undefined && target.uri === evidence.uri);
+
+const evidenceMatches = (
+  target: EvidenceTarget,
+  evidence: RetrievalQrelsEvidence
+): boolean =>
+  sameDocument(target, evidence) &&
+  (target.seq === undefined || target.seq === evidence.seq) &&
+  (target.startLine === undefined || target.startLine === evidence.startLine) &&
+  (target.endLine === undefined || target.endLine === evidence.endLine) &&
+  (target.passageHash === undefined ||
+    target.passageHash === evidence.passageHash);
+
+const effectiveJudgments = (
+  judgments: RetrievalTraceBundle["judgments"]
+): RetrievalTraceBundle["judgments"] => {
+  const latest = new Map<string, RetrievalTraceBundle["judgments"][number]>();
+  for (const judgment of judgments) {
+    const target = stableTarget(judgment.target);
+    if (!target) continue;
+    if (judgment.targetKind === "query") continue;
+    const key = targetKey(judgment.targetKind, target);
+    const previous = latest.get(key);
+    if (
+      !previous ||
+      judgment.createdAtMs > previous.createdAtMs ||
+      (judgment.createdAtMs === previous.createdAtMs &&
+        judgment.judgmentId > previous.judgmentId)
+    ) {
+      latest.set(key, judgment);
+    }
+  }
+  return [...latest.values()].sort((left, right) =>
+    left.judgmentId.localeCompare(right.judgmentId)
+  );
+};
+
+const capabilityOutcomes = (
+  trace: RetrievalTraceBundle,
+  runId: string
+): RetrievalQrelsCase["baseline"]["capabilityOutcomes"] =>
+  trace.events
+    .filter((event) => event.kind === "capability" && event.runId === runId)
+    .flatMap((event) => {
+      const { capability, status, reasonCode } = event.payload;
+      if (
+        typeof capability !== "string" ||
+        !["attempted", "used", "unavailable", "failed"].includes(String(status))
+      ) {
+        return [];
+      }
+      return [
+        {
+          capability,
+          status: status as "attempted" | "used" | "unavailable" | "failed",
+          reasonCode: typeof reasonCode === "string" ? reasonCode : null,
+        },
+      ];
+    })
+    .sort((left, right) =>
+      `${left.capability}\0${left.status}\0${left.reasonCode ?? ""}`.localeCompare(
+        `${right.capability}\0${right.status}\0${right.reasonCode ?? ""}`
+      )
+    );
+
+const outcomeEvidence = (
+  trace: RetrievalTraceBundle,
+  kind: "open" | "cite" | "pin",
+  runId: string
+): RetrievalQrelsEvidence[] =>
+  trace.events
+    .filter((event) => event.kind === kind && event.runId === runId)
+    .flatMap((event) => evidenceArray(event.payload, "evidence"));
+
+const assignedRun = (
+  judgment: RetrievalTraceBundle["judgments"][number],
+  retrievalRuns: RetrievalTraceBundle["runs"]
+): StoreResult<string> => {
+  if (retrievalRuns.some((run) => run.runId === judgment.runId)) {
+    return ok(judgment.runId!);
+  }
+  if (
+    judgment.runId === null &&
+    judgment.label === "missing_expected" &&
+    retrievalRuns.length === 1
+  ) {
+    return ok(retrievalRuns[0]!.runId);
+  }
+  return err(
+    "CONSTRAINT_VIOLATION",
+    "ambiguous_missing_expected_run: judgment cannot be assigned to one retrieval run"
+  );
+};
+
+const sortedStringSet = (value: unknown): string[] =>
+  Array.isArray(value)
+    ? [
+        ...new Set(
+          value.filter((item): item is string => typeof item === "string")
+        ),
+      ].sort()
+    : [];
+
+export const buildRetrievalQrelsArtifact = (
+  bundles: RetrievalTraceBundle[]
+): StoreResult<RetrievalTraceQrelsArtifact> => {
+  const cases: RetrievalQrelsCase[] = [];
+  for (const trace of [...bundles].sort((a, b) =>
+    a.trace.traceId.localeCompare(b.trace.traceId)
+  )) {
+    const header = trace.trace;
+    if (
+      header.status === "open" ||
+      header.redactionMode !== "replay" ||
+      !header.replayCapable
+    ) {
+      return err(
+        "CONSTRAINT_VIOLATION",
+        `redaction_incompatible: ${header.traceId} is not a terminal replay receipt`
+      );
+    }
+    if (!header.queryText || !header.queryDigest) {
+      return err(
+        "CONSTRAINT_VIOLATION",
+        `query_missing: ${header.traceId} lacks replay query text or digest`
+      );
+    }
+    const filters = parseRetrievalTraceFilters(header.filters);
+    if (!filters.ok) return filters;
+    const retrievalRuns = trace.runs.filter((run) => run.kind === "retrieval");
+    if (retrievalRuns.length === 0) {
+      return err("CONSTRAINT_VIOLATION", `no_retrieval_run: ${header.traceId}`);
+    }
+    const rankedByRun = new Map(
+      retrievalRuns.map((run) => [
+        run.runId,
+        evidenceArray(run.payload, "ranked"),
+      ])
+    );
+    const historyByRun = new Map<string, RetrievalTraceBundle["judgments"]>();
+    for (const judgment of trace.judgments) {
+      const assignment = assignedRun(judgment, retrievalRuns);
+      if (!assignment.ok) return assignment;
+      const current = historyByRun.get(assignment.value) ?? [];
+      current.push(judgment);
+      historyByRun.set(assignment.value, current);
+    }
+    const effectiveByRun = new Map<string, RetrievalTraceBundle["judgments"]>();
+    for (const run of retrievalRuns) {
+      effectiveByRun.set(
+        run.runId,
+        effectiveJudgments(historyByRun.get(run.runId) ?? [])
+      );
+    }
+    if (
+      ![...effectiveByRun.values()]
+        .flat()
+        .some(
+          ({ label }) => label === "relevant" || label === "missing_expected"
+        )
+    ) {
+      return err(
+        "CONSTRAINT_VIOLATION",
+        `qrels export requires relevant or missing_expected judgments: ${header.traceId}`
+      );
+    }
+    for (const run of retrievalRuns) {
+      const runJudgments = effectiveByRun.get(run.runId) ?? [];
+      if (runJudgments.length === 0) continue;
+      const runOutcomes = {
+        opened: outcomeEvidence(trace, "open", run.runId),
+        cited: outcomeEvidence(trace, "cite", run.runId),
+        pinned: outcomeEvidence(trace, "pin", run.runId),
+      };
+      const allExact = [
+        ...(rankedByRun.get(run.runId) ?? []),
+        ...runOutcomes.opened,
+        ...runOutcomes.cited,
+        ...runOutcomes.pinned,
+      ];
+      const qrels: RetrievalQrel[] = [];
+      for (const judgment of runJudgments) {
+        const target = stableTarget(judgment.target);
+        if (!target) {
+          return err("CONSTRAINT_VIOLATION", "Judgment target is incomplete");
+        }
+        const evidence =
+          judgment.label === "missing_expected"
+            ? null
+            : (allExact.find((item) => evidenceMatches(target, item)) ?? null);
+        if (judgment.label !== "missing_expected" && !evidence) {
+          return err(
+            "CONSTRAINT_VIOLATION",
+            `Judgment ${judgment.judgmentId} lacks exact evidence provenance`
+          );
+        }
+        qrels.push({
+          qrelId: `qrel-${hashTraceCanonical({
+            judgmentId: judgment.judgmentId,
+            label: judgment.label,
+            target,
+          }).slice(0, 40)}`,
+          judgmentId: judgment.judgmentId,
+          label: judgment.label,
+          relevance: judgment.label === "irrelevant" ? 0 : 1,
+          baselineMissing: judgment.label === "missing_expected",
+          target,
+          evidence,
+        });
+      }
+      cases.push({
+        caseId: `trace-case-${hashTraceCanonical({
+          traceId: header.traceId,
+          runId: run.runId,
+        }).slice(0, 40)}`,
+        traceId: header.traceId,
+        retrievalRunId: run.runId,
+        terminalStatus: header.status,
+        query: {
+          text: header.queryText,
+          digest: header.queryDigest,
+          goalText: header.goalText,
+          goalDigest: header.goalDigest,
+          filters: filters.value,
+        },
+        fingerprints: header.fingerprints,
+        baseline: {
+          ranked: rankedByRun.get(run.runId) ?? [],
+          capabilities: sortedStringSet(run.payload.capabilities),
+          capabilityOutcomes: capabilityOutcomes(trace, run.runId),
+          fallbackCodes: sortedStringSet(run.payload.fallbackCodes),
+          outcomes: runOutcomes,
+        },
+        judgments: {
+          history: (historyByRun.get(run.runId) ?? []).flatMap((judgment) => {
+            const target = stableTarget(judgment.target);
+            return target
+              ? [
+                  {
+                    judgmentId: judgment.judgmentId,
+                    label: judgment.label,
+                    targetKind: judgment.targetKind,
+                    target,
+                    createdAtMs: judgment.createdAtMs,
+                    canonicalDigest: judgment.canonicalDigest,
+                  },
+                ]
+              : [];
+          }),
+          effective: runJudgments.map((judgment) => judgment.judgmentId),
+        },
+        qrels: qrels.sort((a, b) => a.qrelId.localeCompare(b.qrelId)),
+      });
+    }
+  }
+  return ok({
+    schemaVersion: "1.0",
+    format: "qrels",
+    cases: cases.sort((a, b) => a.caseId.localeCompare(b.caseId)),
+  });
+};