@hraness/kb 0.17.1

package/src/evaluation-kb.ts

@@ -0,0 +1,1018 @@
+import { realpath, stat } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+
+import {
+  inspectAgentContextRepository,
+  type AgentContextRepositoryInspection,
+} from "./agent-context.js";
+import {
+  MAX_EVALUATION_EVIDENCE_BYTES,
+  type EvaluationDiagnostic,
+  type EvaluationRawHit,
+  type EvaluationRetriever,
+  type EvaluationRetrieverResult,
+  type RetrievalEvaluationCorpus,
+} from "./evaluation.js";
+import { redactEvaluationMachinePaths } from "./evaluation-redaction.js";
+import {
+  runGitCommand,
+  type GitCommandProvider,
+  type GitHistoryDependencies,
+  type GitHistoryForNotesResult,
+  type GitHistoryNoteProvenance,
+  type GitHistorySearchHit,
+  type GitHistorySearchResult,
+} from "./git.js";
+import {
+  buildRepositoryMemoryContext,
+  MAX_REPOSITORY_MEMORY_DETAIL_LIMIT,
+  MAX_REPOSITORY_MEMORY_GROUP_LIMIT,
+  repositoryMemoryGroupKeys,
+  type RepositoryMemoryContext,
+} from "./repository-memory.js";
+import {
+  MAX_SEARCH_RESULTS,
+  openKnowledgeBase,
+  type KnowledgeBaseDependencies,
+  type KnowledgeBaseSearchMode,
+  type KnowledgeBaseSearchResult,
+  type KnowledgeBaseSession,
+  type OpenKnowledgeBaseOptions,
+} from "./sdk.js";
+import { scanVault, type VaultSnapshot } from "./vault.js";
+
+const objectIdPattern = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/u;
+const SNAPSHOT_GIT_TIMEOUT_MS = 10_000;
+const SNAPSHOT_GIT_OUTPUT_BYTES = 64 * 1_024;
+const DIAGNOSTIC_MESSAGE_BYTES = 16 * 1_024;
+
+export const knowledgeBaseEvaluationRetrieverIds = Object.freeze([
+  "exact",
+  "keyword",
+  "semantic",
+  "hybrid",
+  "metadata",
+  "graph",
+  "path-context",
+  "git",
+] as const);
+
+export type KnowledgeBaseEvaluationRetrieverId =
+  typeof knowledgeBaseEvaluationRetrieverIds[number];
+
+type CanonicalPathDependencies = {
+  readonly realpath?: (path: string) => Promise<string>;
+  readonly stat?: (path: string) => Promise<{ readonly isDirectory: () => boolean }>;
+};
+
+export type VerifyFrozenEvaluationSnapshotOptions = CanonicalPathDependencies & {
+  readonly corpus: Pick<RetrievalEvaluationCorpus, "frozen">;
+  readonly root: string;
+  readonly repository: string;
+  readonly runGit?: GitCommandProvider;
+};
+
+export type FrozenEvaluationSnapshot = {
+  readonly repository: string;
+  readonly root: string;
+  readonly vaultRoot: string;
+  readonly repositoryCommit: string;
+  readonly vaultTree: string;
+};
+
+export class FrozenEvaluationSnapshotError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "FrozenEvaluationSnapshotError";
+  }
+}
+
+export type OpenKnowledgeBaseEvaluationOptions = CanonicalPathDependencies & {
+  readonly corpus: RetrievalEvaluationCorpus;
+  readonly root: string;
+  readonly repository: string;
+  readonly database?: string;
+  /** Verified local bytes for the pinned semantic model. */
+  readonly embeddingModelFile?: string;
+  /** Shared opaque lease for verified local bytes across evaluator readers. */
+  readonly embeddingModelLease?: OpenKnowledgeBaseOptions["embeddingModelLease"];
+  /** Require measurable store-local query-vector inference. */
+  readonly requireStoreLocalVectorBoundary?: boolean;
+  readonly runGit?: GitCommandProvider;
+  readonly scanVault?: typeof scanVault;
+  readonly openKnowledgeBase?: typeof openKnowledgeBase;
+  readonly inspectAgentContextRepository?: typeof inspectAgentContextRepository;
+  readonly buildRepositoryMemoryContext?: typeof buildRepositoryMemoryContext;
+  readonly semantic?: KnowledgeBaseDependencies["semantic"];
+  readonly openSemanticSearchSession?: KnowledgeBaseDependencies["openSemanticSearchSession"];
+  readonly git?: GitHistoryDependencies;
+  readonly indexGitHistory?: KnowledgeBaseDependencies["indexGitHistory"];
+  readonly now?: () => number;
+};
+
+export type KnowledgeBaseEvaluation = {
+  readonly retrievers: readonly EvaluationRetriever[];
+  readonly close: () => Promise<void>;
+};
+
+function pathIsWithin(root: string, candidate: string): boolean {
+  const fromRoot = relative(root, candidate);
+  return fromRoot === ""
+    || (
+      fromRoot !== ".."
+      && !fromRoot.startsWith(`..${sep}`)
+      && !isAbsolute(fromRoot)
+    );
+}
+
+function decodedOutput(
+  output: string | Uint8Array,
+  label: string,
+  maximumBytes = SNAPSHOT_GIT_OUTPUT_BYTES,
+): string {
+  const bytes = typeof output === "string" ? Buffer.from(output, "utf8") : Buffer.from(output);
+  if (bytes.byteLength > maximumBytes) {
+    throw new FrozenEvaluationSnapshotError(
+      `${label} exceeded the ${maximumBytes.toLocaleString("en-US")}-byte output limit.`,
+    );
+  }
+  return bytes.toString("utf8");
+}
+
+async function gitOutput(
+  runGit: GitCommandProvider,
+  repository: string,
+  args: readonly string[],
+  label: string,
+): Promise<string> {
+  const result = await runGit({
+    arguments: args,
+    cwd: repository,
+    timeoutMs: SNAPSHOT_GIT_TIMEOUT_MS,
+    maxOutputBytes: SNAPSHOT_GIT_OUTPUT_BYTES,
+  });
+  if (result.status !== "ok") {
+    throw new FrozenEvaluationSnapshotError(
+      `${label} could not be verified: ${result.status === "unavailable" ? result.message : result.message}`,
+    );
+  }
+  return decodedOutput(result.stdout, label);
+}
+
+function gitObjectId(output: string, label: string): string {
+  const value = output.trim();
+  if (!objectIdPattern.test(value)) {
+    throw new FrozenEvaluationSnapshotError(`${label} returned a malformed Git object ID.`);
+  }
+  return value;
+}
+
+/**
+ * Verify that a corpus names the checked-out, clean vault snapshot it will read.
+ * All Git work uses bounded argv requests and never invokes a shell.
+ */
+export async function verifyFrozenEvaluationSnapshot(
+  options: VerifyFrozenEvaluationSnapshotOptions,
+): Promise<FrozenEvaluationSnapshot> {
+  const resolveRealpath = options.realpath ?? realpath;
+  const readStat = options.stat ?? stat;
+  const repository = await resolveRealpath(resolve(options.repository));
+  const repositoryState = await readStat(repository);
+  if (!repositoryState.isDirectory()) {
+    throw new FrozenEvaluationSnapshotError("The evaluation repository must be a directory.");
+  }
+
+  const root = await resolveRealpath(resolve(options.root));
+  const rootState = await readStat(root);
+  if (!rootState.isDirectory()) {
+    throw new FrozenEvaluationSnapshotError("The evaluation vault root must be a directory.");
+  }
+  if (!pathIsWithin(repository, root)) {
+    throw new FrozenEvaluationSnapshotError(
+      "The evaluation vault root must resolve inside the repository.",
+    );
+  }
+
+  const declaredRoot = await resolveRealpath(resolve(repository, options.corpus.frozen.vaultRoot));
+  if (!pathIsWithin(repository, declaredRoot) || declaredRoot !== root) {
+    throw new FrozenEvaluationSnapshotError(
+      "The evaluation vault root must resolve to frozen.vaultRoot inside the repository.",
+    );
+  }
+
+  const runGit = options.runGit ?? runGitCommand;
+  const repositoryPrefix = (await gitOutput(
+    runGit,
+    repository,
+    ["rev-parse", "--show-prefix"],
+    "Git repository root",
+  )).trim();
+  if (repositoryPrefix !== "") {
+    throw new FrozenEvaluationSnapshotError(
+      `The evaluation repository must be the Git working-tree root; Git reported prefix ${JSON.stringify(repositoryPrefix)}.`,
+    );
+  }
+  const head = gitObjectId(
+    await gitOutput(runGit, repository, ["rev-parse", "--verify", "HEAD"], "Git HEAD"),
+    "Git HEAD",
+  );
+  if (head !== options.corpus.frozen.repositoryCommit) {
+    throw new FrozenEvaluationSnapshotError(
+      `Frozen repository commit ${options.corpus.frozen.repositoryCommit} does not match HEAD ${head}.`,
+    );
+  }
+
+  const vaultRevision = options.corpus.frozen.vaultRoot === "."
+    ? "HEAD^{tree}"
+    : `HEAD:${options.corpus.frozen.vaultRoot}`;
+  const vaultTree = gitObjectId(
+    await gitOutput(
+      runGit,
+      repository,
+      ["rev-parse", "--verify", vaultRevision],
+      "Git vault tree",
+    ),
+    "Git vault tree",
+  );
+  if (vaultTree !== options.corpus.frozen.vaultTree) {
+    throw new FrozenEvaluationSnapshotError(
+      `Frozen vault tree ${options.corpus.frozen.vaultTree} does not match ${vaultRevision} ${vaultTree}.`,
+    );
+  }
+
+  const objectType = (await gitOutput(
+    runGit,
+    repository,
+    ["cat-file", "-t", vaultRevision],
+    "Git vault object type",
+  )).trim();
+  if (objectType !== "tree") {
+    throw new FrozenEvaluationSnapshotError(
+      `${vaultRevision} must identify a Git tree, but Git reported ${JSON.stringify(objectType)}.`,
+    );
+  }
+
+  const status = await gitOutput(
+    runGit,
+    repository,
+    [
+      "status",
+      "--porcelain=v1",
+      "--untracked-files=all",
+      "--",
+      options.corpus.frozen.vaultRoot,
+    ],
+    "Git vault status",
+  );
+  if (status.trim() !== "") {
+    const firstChange = status.trim().split(/\r?\n/u)[0] ?? "unknown vault change";
+    throw new FrozenEvaluationSnapshotError(
+      `The frozen evaluation vault has tracked or untracked changes: ${firstChange}.`,
+    );
+  }
+
+  return Object.freeze({
+    repository,
+    root,
+    vaultRoot: options.corpus.frozen.vaultRoot,
+    repositoryCommit: head,
+    vaultTree,
+  });
+}
+
+function elapsed(startedAt: number, now: () => number): number {
+  const duration = now() - startedAt;
+  return Number.isFinite(duration) && duration > 0 ? duration : 0;
+}
+
+function utf8Prefix(value: string, maximumBytes: number): string {
+  let bytes = 0;
+  let end = 0;
+  for (const character of value) {
+    const width = Buffer.byteLength(character, "utf8");
+    if (bytes + width > maximumBytes) break;
+    bytes += width;
+    end += character.length;
+  }
+  return value.slice(0, end);
+}
+
+function diagnosticMessage(parts: readonly string[]): string | undefined {
+  const joined = redactEvaluationMachinePaths(parts
+    .join(" ")
+    .normalize("NFC")
+    .replace(/[\0\r\n]+/gu, " ")
+    .trim());
+  if (joined === "") return undefined;
+  return utf8Prefix(joined, DIAGNOSTIC_MESSAGE_BYTES);
+}
+
+function evidenceSnapshot(value: unknown): unknown {
+  const serialized = JSON.stringify(value, (_key, candidate: unknown) =>
+    typeof candidate === "string" ? redactEvaluationMachinePaths(candidate) : candidate);
+  if (serialized === undefined) return null;
+  const bytes = Buffer.byteLength(serialized, "utf8");
+  if (bytes <= MAX_EVALUATION_EVIDENCE_BYTES) {
+    return JSON.parse(serialized) as unknown;
+  }
+  let prefixBytes = MAX_EVALUATION_EVIDENCE_BYTES - 1_024;
+  while (prefixBytes > 0) {
+    const snapshot = {
+      truncated: true,
+      originalUtf8Bytes: bytes,
+      jsonPrefix: utf8Prefix(serialized, prefixBytes),
+    };
+    if (Buffer.byteLength(JSON.stringify(snapshot), "utf8") <= MAX_EVALUATION_EVIDENCE_BYTES) {
+      return snapshot;
+    }
+    prefixBytes = Math.floor(prefixBytes * 0.75);
+  }
+  return { truncated: true, originalUtf8Bytes: bytes, jsonPrefix: "" };
+}
+
+function unavailable(
+  id: KnowledgeBaseEvaluationRetrieverId,
+  requiredInput: string,
+  noteCount: number,
+): EvaluationRetrieverResult {
+  return Object.freeze({
+    status: "unavailable",
+    hits: Object.freeze([]),
+    diagnostics: Object.freeze([Object.freeze({
+      lane: id,
+      status: "unavailable",
+      message: `${id} retrieval requires ${requiredInput}.`,
+    })]),
+    timings: Object.freeze({}),
+    resources: Object.freeze({ noteCount }),
+  });
+}
+
+type LaneEvidenceProvenance = Readonly<{
+  readonly targetDocumentId: string;
+  readonly evidenceDocumentId: string;
+  readonly sourcePath: string;
+  readonly locator: Readonly<Record<string, unknown>>;
+}>;
+
+function textHitProvenance(
+  hit: KnowledgeBaseSearchResult["results"][number],
+): readonly LaneEvidenceProvenance[] {
+  const exactEvidence = hit.evidence.find((evidence) => evidence.kind === "exact");
+  const qmdEvidence = hit.evidence.filter((evidence) => evidence.kind === "qmd");
+  const explicitLocators = hit.evidence.flatMap((evidence) => evidence.kind !== "exact"
+    ? []
+    : evidence.matches.flatMap((match): readonly Readonly<Record<string, unknown>>[] => {
+        if (match.field === "title") {
+          return [Object.freeze({ kind: "title", title: hit.title })];
+        }
+        if (match.field === "alias") {
+          return [Object.freeze({
+            kind: "frontmatter-field-any",
+            fields: Object.freeze(["aliases", "alias"]),
+          })];
+        }
+        if (match.field === "tag") {
+          return [Object.freeze({ kind: "frontmatter-field", field: "tags" })];
+        }
+        if (match.field === "metadata") {
+          return [Object.freeze({ kind: "frontmatter-value", value: match.value })];
+        }
+        if (match.field === "path") {
+          return [Object.freeze({ kind: "source-path", sourcePath: hit.path })];
+        }
+        return [];
+      }));
+  const exactContentLocators = hit.line !== undefined
+    && exactEvidence?.matches.some(({ field }) => field === "content") === true
+    && (exactEvidence.identity || qmdEvidence.length === 0)
+      ? [Object.freeze({ kind: "line", line: hit.line })]
+      : [];
+  const sameDocumentLocators = [...explicitLocators, ...exactContentLocators];
+  const sameDocument = sameDocumentLocators.map((locator) => Object.freeze({
+    targetDocumentId: hit.id,
+    evidenceDocumentId: hit.id,
+    sourcePath: hit.path,
+    locator,
+  }));
+  const qmd = qmdEvidence.flatMap((evidence) => evidence.line === undefined || evidence.path === undefined
+    ? []
+    : [Object.freeze({
+        targetDocumentId: hit.id,
+        evidenceDocumentId: hit.id,
+        sourcePath: evidence.path,
+        locator: Object.freeze({ kind: "line", line: evidence.line }),
+      })]);
+  const unique = [...new Map([...sameDocument, ...qmd].map((provenance) =>
+    [JSON.stringify(provenance), provenance])).values()];
+  return Object.freeze(unique);
+}
+
+function statusFromDiagnostics(
+  diagnostics: readonly EvaluationDiagnostic[],
+  hits: readonly EvaluationRawHit[],
+): EvaluationRetrieverResult["status"] {
+  if (
+    hits.length === 0
+    && diagnostics.length > 0
+    && diagnostics.every(({ status }) => status === "unavailable")
+  ) return "unavailable";
+  return diagnostics.some(({ status }) => status !== "ready") ? "degraded" : "ready";
+}
+
+function textResult(result: KnowledgeBaseSearchResult): EvaluationRetrieverResult {
+  const hits = Object.freeze(result.results.map((hit): EvaluationRawHit => {
+    const provenance = textHitProvenance(hit);
+    return Object.freeze({
+      documentId: hit.id,
+      rank: hit.rank,
+      score: hit.score,
+      evidence: evidenceSnapshot({
+        mode: result.mode,
+        path: hit.path,
+        title: hit.title,
+        identity: hit.identity,
+        ...(hit.line === undefined ? {} : { line: hit.line }),
+        snippet: hit.snippet,
+        evidence: hit.evidence,
+        contributions: hit.contributions,
+        ...(provenance.length === 0 ? {} : { provenance }),
+      }),
+    });
+  }));
+  const diagnostics = Object.freeze(result.diagnostics.lanes.map((lane): EvaluationDiagnostic =>
+    Object.freeze({
+      lane: lane.lane,
+      status: lane.status,
+      ...(lane.message === undefined
+        ? {}
+        : { message: diagnosticMessage([lane.message]) ?? "Search diagnostic unavailable." }),
+    })));
+  const laneResults = new Map(result.diagnostics.lanes.map(({ lane, results }) => [lane, results]));
+  return Object.freeze({
+    status: statusFromDiagnostics(diagnostics, hits),
+    hits,
+    diagnostics,
+    timings: Object.freeze({ searchMs: result.diagnostics.elapsedMs }),
+    resources: Object.freeze({
+      noteCount: result.diagnostics.notes,
+      resultCount: result.results.length,
+      partial: Number(result.partial),
+      exactResultCount: laneResults.get("exact") ?? 0,
+      qmdResultCount: laneResults.get("qmd") ?? 0,
+      ...(result.diagnostics.queryEmbedding == null
+        ? {}
+        : {
+            queryEmbeddingCalls: result.diagnostics.queryEmbedding.calls,
+            queryEmbeddingInputTokens: result.diagnostics.queryEmbedding.inputTokens,
+            queryEmbeddingDurationMs: result.diagnostics.queryEmbedding.durationMs,
+          }),
+    }),
+  });
+}
+
+function stableHits(
+  candidates: readonly {
+    readonly documentId: string;
+    readonly score?: number;
+    readonly evidence: unknown;
+  }[],
+  limit: number,
+): readonly EvaluationRawHit[] {
+  const unique = new Map<string, typeof candidates[number]>();
+  for (const candidate of candidates) {
+    if (!unique.has(candidate.documentId)) unique.set(candidate.documentId, candidate);
+  }
+  return Object.freeze([...unique.values()].slice(0, limit).map((candidate, index) =>
+    Object.freeze({
+      documentId: candidate.documentId,
+      rank: index + 1,
+      ...(candidate.score === undefined ? {} : { score: candidate.score }),
+      evidence: evidenceSnapshot(candidate.evidence),
+    })));
+}
+
+function metadataRetriever(
+  session: KnowledgeBaseSession,
+  now: () => number,
+): EvaluationRetriever {
+  return Object.freeze({
+    id: "metadata",
+    retrieve: ({ query, limit, signal }) => {
+      if (query.inputs.metadata === undefined) {
+        return Promise.resolve(unavailable("metadata", "query.inputs.metadata", session.noteCount));
+      }
+      throwIfAborted(signal);
+      const startedAt = now();
+      const rows = session.list({
+        filters: query.inputs.metadata.filters,
+        tags: query.inputs.metadata.tags,
+        limit,
+      });
+      throwIfAborted(signal);
+      const provenanceFields = [
+        ...query.inputs.metadata.filters.map(({ path }) => path.split(".")[0]),
+        ...(query.inputs.metadata.tags.length === 0 ? [] : ["tags"]),
+      ].filter((field): field is string => field !== undefined && field !== "");
+      const provenanceFieldList = [...new Set(provenanceFields)];
+      const hits = Object.freeze(rows.map((row, index): EvaluationRawHit => Object.freeze({
+        documentId: row.id,
+        rank: index + 1,
+        evidence: evidenceSnapshot({
+          ...row,
+          ...(provenanceFieldList.length === 0
+            ? {}
+            : {
+                provenance: provenanceFieldList.map((field) => ({
+                  targetDocumentId: row.id,
+                  evidenceDocumentId: row.id,
+                  sourcePath: row.path,
+                  locator: { kind: "frontmatter-field", field },
+                })),
+              }),
+        }),
+      })));
+      return Promise.resolve(Object.freeze({
+        status: "ready",
+        hits,
+        diagnostics: Object.freeze([Object.freeze({
+          lane: "metadata",
+          status: "ready",
+        })]),
+        timings: Object.freeze({ listMs: elapsed(startedAt, now) }),
+        resources: Object.freeze({ noteCount: session.noteCount, resultCount: rows.length }),
+      }));
+    },
+  });
+}
+
+function graphRetriever(
+  session: KnowledgeBaseSession,
+  now: () => number,
+): EvaluationRetriever {
+  return Object.freeze({
+    id: "graph",
+    retrieve: ({ query, limit, signal }) => {
+      const input = query.inputs.graph;
+      if (input === undefined) {
+        return Promise.resolve(unavailable("graph", "query.inputs.graph", session.noteCount));
+      }
+      throwIfAborted(signal);
+      const startedAt = now();
+      type GraphEvidenceProvenance = Readonly<{
+        readonly targetDocumentId: string;
+        readonly evidenceDocumentId: string;
+        readonly sourcePath: string;
+        readonly locator: Readonly<{ readonly kind: "line"; readonly line: number }>;
+      }>;
+      const matches = new Map<string, {
+        readonly documentId: string;
+        readonly distance: number;
+        readonly seedIndex: number;
+        readonly nodeIndex: number;
+        readonly evidence: Array<Readonly<{
+          readonly seed: string;
+          readonly node: unknown;
+          readonly connections: readonly unknown[];
+          readonly provenance?: readonly GraphEvidenceProvenance[];
+        }>>;
+      }>();
+      const diagnostics: EvaluationDiagnostic[] = [];
+      let edges = 0;
+      let relations = 0;
+      for (const [seedIndex, seed] of input.seeds.entries()) {
+        const neighborhood = session.links(seed, {
+          direction: "both",
+          depth: input.depth,
+          limit,
+        });
+        edges += neighborhood.edges.length;
+        relations += neighborhood.relations.length;
+        diagnostics.push(Object.freeze({
+          lane: "graph",
+          status: neighborhood.truncated ? "degraded" : "ready",
+          ...(neighborhood.truncated
+            ? { message: `Graph traversal from ${JSON.stringify(seed)} reached its result limit.` }
+            : {}),
+        }));
+        const nodeIdByPath = new Map(neighborhood.nodes.map((node) => [node.path, node.id]));
+        for (const [nodeIndex, node] of neighborhood.nodes.entries()) {
+          const links = neighborhood.edges.filter((edge) =>
+            edge.source === node.path || edge.target === node.path);
+          const authoredRelations = neighborhood.relations.filter((relation) =>
+            relation.source === node.id || relation.target === node.id);
+          const connections = Object.freeze([
+            ...links.map((edge) => Object.freeze({ kind: "link" as const, edge })),
+            ...authoredRelations.map((relation) => Object.freeze({
+              kind: "relation" as const,
+              relation,
+            })),
+          ]);
+          const provenance = Object.freeze([...new Map([
+            ...links.flatMap((link): readonly GraphEvidenceProvenance[] => {
+              const evidenceDocumentId = nodeIdByPath.get(link.source);
+              return evidenceDocumentId === undefined ? [] : [Object.freeze({
+                targetDocumentId: node.id,
+                evidenceDocumentId,
+                sourcePath: link.source,
+                locator: Object.freeze({ kind: "line" as const, line: link.line }),
+              })];
+            }),
+            ...authoredRelations.map((relation): GraphEvidenceProvenance => Object.freeze({
+              targetDocumentId: node.id,
+              evidenceDocumentId: relation.source,
+              sourcePath: relation.provenance.source,
+              locator: Object.freeze({
+                kind: "line" as const,
+                line: relation.provenance.line,
+              }),
+            })),
+          ].map((candidate) => [JSON.stringify(candidate), candidate])).values()]);
+          const raw = Object.freeze({
+            seed,
+            node,
+            connections,
+            ...(provenance.length === 0 ? {} : { provenance }),
+          });
+          const existing = matches.get(node.id);
+          if (existing === undefined) {
+            matches.set(node.id, {
+              documentId: node.id,
+              distance: node.distance,
+              seedIndex,
+              nodeIndex,
+              evidence: [raw],
+            });
+          } else {
+            existing.evidence.push(raw);
+          }
+        }
+      }
+      const candidates = [...matches.values()].toSorted((left, right) =>
+        left.distance - right.distance
+        || left.seedIndex - right.seedIndex
+        || left.nodeIndex - right.nodeIndex
+        || left.documentId.localeCompare(right.documentId));
+      const hits = stableHits(candidates.map((candidate) => ({
+        documentId: candidate.documentId,
+        score: 1 / (candidate.distance + 1),
+        evidence: {
+          neighborhoods: candidate.evidence,
+          ...(() => {
+            const provenance = [...new Map(candidate.evidence
+              .flatMap((entry) => entry.provenance ?? [])
+              .map((entry) => [JSON.stringify(entry), entry])).values()];
+            return provenance.length === 0 ? {} : { provenance: Object.freeze(provenance) };
+          })(),
+        },
+      })), limit);
+      throwIfAborted(signal);
+      return Promise.resolve(Object.freeze({
+        status: statusFromDiagnostics(diagnostics, hits),
+        hits,
+        diagnostics: Object.freeze(diagnostics),
+        timings: Object.freeze({ linksMs: elapsed(startedAt, now) }),
+        resources: Object.freeze({
+          noteCount: session.noteCount,
+          seedCount: input.seeds.length,
+          resultCount: hits.length,
+          edgeCount: edges,
+          relationCount: relations,
+        }),
+      }));
+    },
+  });
+}
+
+function pathContextDiagnostics(
+  inspection: AgentContextRepositoryInspection,
+  memory: RepositoryMemoryContext,
+): readonly EvaluationDiagnostic[] {
+  const inspectionMessage = diagnosticMessage(
+    inspection.issues.map(({ message }) => message),
+  );
+  const memoryMessages = [
+    ...memory.invalidRecords.details.flatMap(({ issues }) => issues),
+    ...memory.advisories.details.map(({ message }) => message),
+    ...(repositoryMemoryGroupKeys.some((key) => memory.groups[key].truncated)
+      ? ["Repository-memory results were truncated by the evaluation limit."]
+      : []),
+  ];
+  const memoryMessage = diagnosticMessage(memoryMessages);
+  return Object.freeze([
+    Object.freeze({
+      lane: "agent-context",
+      status: inspection.issues.length === 0 ? "ready" : "degraded",
+      ...(inspectionMessage === undefined ? {} : { message: inspectionMessage }),
+    }),
+    Object.freeze({
+      lane: "repository-memory",
+      status: memoryMessages.length === 0 ? "ready" : "degraded",
+      ...(memoryMessage === undefined ? {} : { message: memoryMessage }),
+    }),
+  ]);
+}
+
+function pathContextRetriever(
+  session: KnowledgeBaseSession,
+  snapshot: VaultSnapshot,
+  repository: string,
+  inspectContext: typeof inspectAgentContextRepository,
+  buildMemory: typeof buildRepositoryMemoryContext,
+  now: () => number,
+): EvaluationRetriever {
+  return Object.freeze({
+    id: "path-context",
+    retrieve: async ({ query, limit, signal }) => {
+      const input = query.inputs.context;
+      if (input === undefined) {
+        return unavailable("path-context", "query.inputs.context", session.noteCount);
+      }
+      throwIfAborted(signal);
+      const inspectionStartedAt = now();
+      const inspection = await inspectContext(snapshot.notes, {
+        repositoryRoot: repository,
+        target: input.repositoryPath,
+        targetKind: "auto",
+      });
+      const inspectionMs = elapsed(inspectionStartedAt, now);
+      throwIfAborted(signal);
+      const memoryStartedAt = now();
+      const memory = await buildMemory(snapshot.notes, {
+        repositoryRoot: repository,
+        target: input.repositoryPath,
+        groupLimit: Math.min(limit, MAX_REPOSITORY_MEMORY_GROUP_LIMIT),
+        detailLimit: Math.min(limit, MAX_REPOSITORY_MEMORY_DETAIL_LIMIT),
+      });
+      const memoryMs = elapsed(memoryStartedAt, now);
+      throwIfAborted(signal);
+
+      const candidates = [
+        ...inspection.matchingContexts.map((hub) => ({
+          documentId: hub.note.id,
+          evidence: {
+            kind: "agent-context",
+            path: hub.note.path,
+            rawScope: hub.rawScope,
+            scope: hub.scope,
+            canonicalId: hub.canonicalId,
+            canonicalPath: hub.canonicalPath,
+            guidePath: hub.guidePath,
+            canonical: hub.canonical,
+            reciprocal: hub.reciprocal,
+            valid: hub.valid,
+            provenance: [{
+              targetDocumentId: hub.note.id,
+              evidenceDocumentId: hub.note.id,
+              sourcePath: hub.note.path,
+              locator: { kind: "frontmatter-field", field: "scope" },
+            }],
+          },
+        })),
+        ...repositoryMemoryGroupKeys.flatMap((group) =>
+          memory.groups[group].records.map((record) => ({
+            documentId: record.id,
+            evidence: {
+              kind: "repository-memory",
+              group,
+              record,
+              provenance: [{
+                targetDocumentId: record.id,
+                evidenceDocumentId: record.id,
+                sourcePath: record.path,
+                locator: { kind: "frontmatter-field", field: "repository_scopes" },
+              }],
+            },
+          }))),
+      ];
+      const hits = stableHits(candidates, limit);
+      const diagnostics = pathContextDiagnostics(inspection, memory);
+      return Object.freeze({
+        status: statusFromDiagnostics(diagnostics, hits),
+        hits,
+        diagnostics,
+        timings: Object.freeze({ inspectionMs, memoryMs }),
+        resources: Object.freeze({
+          noteCount: session.noteCount,
+          resultCount: hits.length,
+          matchingContextCount: inspection.matchingContexts.length,
+          inheritedGuideCount: inspection.inheritedGuides.length,
+          contextIssueCount: inspection.issues.length,
+          memoryMatchedCount: memory.counts.matched,
+          memoryReturnedCount: memory.counts.returned,
+          memoryInvalidCount: memory.counts.invalid,
+          memoryAdvisoryCount: memory.counts.advisories,
+        }),
+      });
+    },
+  });
+}
+
+function gitDiagnostic(
+  lane: "git-search" | "git-history",
+  result: GitHistorySearchResult | GitHistoryForNotesResult,
+): EvaluationDiagnostic {
+  if (result.status === "unavailable") {
+    return Object.freeze({
+      lane,
+      status: "unavailable",
+      message: diagnosticMessage([result.reason]) ?? "Git retrieval is unavailable.",
+    });
+  }
+  const limited = result.limitedCommits ?? [];
+  return Object.freeze({
+    lane,
+    status: limited.length === 0 ? "ready" : "degraded",
+    ...(limited.length === 0
+      ? {}
+      : { message: `${limited.length} oversized Git commit record(s) have limited evidence.` }),
+  });
+}
+
+function gitRetriever(
+  session: KnowledgeBaseSession,
+  frozenCommit: string,
+  now: () => number,
+): EvaluationRetriever {
+  return Object.freeze({
+    id: "git",
+    retrieve: async ({ query, limit, signal }) => {
+      const input = query.inputs.history;
+      if (input === undefined) {
+        return unavailable("git", "query.inputs.history", session.noteCount);
+      }
+      throwIfAborted(signal);
+      const searchStartedAt = now();
+      const searched = await session.searchHistory({
+        query: input.query,
+        limit: Math.min(limit, 100),
+      });
+      const searchMs = elapsed(searchStartedAt, now);
+      throwIfAborted(signal);
+      const historyStartedAt = now();
+      const history = await session.history(input.noteIds);
+      const historyMs = elapsed(historyStartedAt, now);
+      throwIfAborted(signal);
+
+      for (const result of [searched, history]) {
+        if (result.status === "ready" && result.head !== frozenCommit) {
+          throw new FrozenEvaluationSnapshotError(
+            `Git retrieval observed HEAD ${result.head}, expected frozen commit ${frozenCommit}.`,
+          );
+        }
+      }
+
+      const searchedById = new Map<string, GitHistorySearchHit>(
+        searched.status === "ready"
+          ? searched.hits.map((hit) => [hit.id, hit])
+          : [],
+      );
+      const historyById = new Map<string, GitHistoryNoteProvenance>(
+        history.status === "ready"
+          ? history.notes.map((note) => [note.id, note])
+          : [],
+      );
+      const orderedIds = [
+        ...input.noteIds.filter((id) => historyById.has(id)),
+        ...(searched.status === "ready" ? searched.hits.map(({ id }) => id) : []),
+      ];
+      const candidates = orderedIds.map((documentId) => {
+        const searchedHit = searchedById.get(documentId);
+        const provenance = historyById.get(documentId);
+        return {
+          documentId,
+          ...(searchedHit === undefined ? {} : { score: searchedHit.score }),
+          evidence: {
+            ...(provenance === undefined ? {} : { history: provenance }),
+            ...(searchedHit === undefined ? {} : { search: searchedHit }),
+          },
+        };
+      });
+      const hits = stableHits(candidates, limit);
+      const diagnostics = Object.freeze([
+        gitDiagnostic("git-search", searched),
+        gitDiagnostic("git-history", history),
+      ]);
+      const searchedLimited = searched.status === "ready" ? searched.limitedCommits?.length ?? 0 : 0;
+      const historyLimited = history.status === "ready" ? history.limitedCommits?.length ?? 0 : 0;
+      return Object.freeze({
+        status: statusFromDiagnostics(diagnostics, hits),
+        hits,
+        diagnostics,
+        timings: Object.freeze({ searchHistoryMs: searchMs, historyMs }),
+        resources: Object.freeze({
+          noteCount: session.noteCount,
+          resultCount: hits.length,
+          searchResultCount: searched.status === "ready" ? searched.hits.length : 0,
+          historyResultCount: history.status === "ready" ? history.notes.length : 0,
+          limitedCommitCount: searchedLimited + historyLimited,
+        }),
+      });
+    },
+  });
+}
+
+function throwIfAborted(signal: AbortSignal): void {
+  if (!signal.aborted) return;
+  if (signal.reason instanceof Error) throw signal.reason;
+  throw new Error("Knowledge-base evaluation retrieval was aborted.");
+}
+
+function textRetriever(
+  id: "exact" | "keyword" | "semantic" | "hybrid",
+  session: KnowledgeBaseSession,
+): EvaluationRetriever {
+  return Object.freeze({
+    id,
+    retrieve: async ({ query, limit, signal }) => {
+      const text = query.inputs.text;
+      if (text === undefined) return unavailable(id, "query.inputs.text", session.noteCount);
+      throwIfAborted(signal);
+      const result = await session.search({
+        query: text,
+        mode: id satisfies KnowledgeBaseSearchMode,
+        limit: Math.min(limit, MAX_SEARCH_RESULTS),
+        graph: false,
+        history: false,
+      });
+      throwIfAborted(signal);
+      return textResult(result);
+    },
+  });
+}
+
+function knowledgeBaseDependencies(
+  options: OpenKnowledgeBaseEvaluationOptions,
+  snapshot: VaultSnapshot,
+): KnowledgeBaseDependencies {
+  const git = options.git === undefined && options.runGit === undefined
+    ? undefined
+    : {
+        ...options.git,
+        ...(options.git?.runGit !== undefined || options.runGit === undefined
+          ? {}
+          : { runGit: options.runGit }),
+      };
+  return {
+    scanVault: () => Promise.resolve(snapshot),
+    ...(options.semantic === undefined ? {} : { semantic: options.semantic }),
+    ...(options.openSemanticSearchSession === undefined
+      ? {}
+      : { openSemanticSearchSession: options.openSemanticSearchSession }),
+    ...(git === undefined ? {} : { git }),
+    ...(options.indexGitHistory === undefined
+      ? {}
+      : { indexGitHistory: options.indexGitHistory }),
+  };
+}
+
+/** Open all built-in evaluation lanes over one verified, immutable vault scan. */
+export async function openKnowledgeBaseEvaluation(
+  options: OpenKnowledgeBaseEvaluationOptions,
+): Promise<KnowledgeBaseEvaluation> {
+  const verified = await verifyFrozenEvaluationSnapshot(options);
+  const scanner = options.scanVault ?? scanVault;
+  const snapshot = await scanner(verified.root, { mentionScope: false });
+  const open = options.openKnowledgeBase ?? openKnowledgeBase;
+  const session = await open(
+    {
+      root: verified.root,
+      repository: verified.repository,
+      ...(options.database === undefined ? {} : { database: options.database }),
+      ...(options.embeddingModelFile === undefined
+        ? {}
+        : { embeddingModelFile: options.embeddingModelFile }),
+      ...(options.embeddingModelLease === undefined
+        ? {}
+        : { embeddingModelLease: options.embeddingModelLease }),
+      ...(options.requireStoreLocalVectorBoundary === undefined
+        ? {}
+        : {
+            requireStoreLocalVectorBoundary:
+              options.requireStoreLocalVectorBoundary,
+          }),
+    },
+    knowledgeBaseDependencies(options, snapshot),
+  );
+  const now = options.now ?? performance.now.bind(performance);
+  const inspectContext = options.inspectAgentContextRepository ?? inspectAgentContextRepository;
+  const buildMemory = options.buildRepositoryMemoryContext ?? buildRepositoryMemoryContext;
+  const retrievers = Object.freeze([
+    textRetriever("exact", session),
+    textRetriever("keyword", session),
+    textRetriever("semantic", session),
+    textRetriever("hybrid", session),
+    metadataRetriever(session, now),
+    graphRetriever(session, now),
+    pathContextRetriever(
+      session,
+      snapshot,
+      verified.repository,
+      inspectContext,
+      buildMemory,
+      now,
+    ),
+    gitRetriever(session, verified.repositoryCommit, now),
+  ] satisfies readonly EvaluationRetriever[]);
+  return Object.freeze({ retrievers, close: session.close });
+}