@gmickel/gno 2.10.1 → 2.12.0

package/src/pipeline/fusion.ts

@@ -35,6 +35,15 @@ function rrfContribution(rank: number, k: number, weight: number): number {
   return weight / (k + rank);
 }
 
+/**
+ * Candidates are documents: BM25 ranks whole documents while vector search
+ * ranks chunks, so a chunk-level key would split one document's votes across
+ * its chunks. Each list counts a document once, at its best rank.
+ */
+function fusionKey(result: RankedInput["results"][number]): string {
+  return `${result.documentId ?? result.mirrorHash}`;
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Fusion Implementation
 // ─────────────────────────────────────────────────────────────────────────────
@@ -51,7 +60,7 @@ export function rrfFuse(
   inputs: RankedInput[],
   config: RrfConfig
 ): FusionCandidate[] {
-  // Map: "mirrorHash:seq" -> FusionCandidate
+  // Map: document key -> FusionCandidate
   const candidates = new Map<string, FusionCandidate>();
 
   // Separate inputs by type for weight assignment
@@ -74,8 +83,11 @@ export function rrfFuse(
         ? config.bm25Weight * 2.0
         : config.bm25Weight * 0.5;
 
+    const countedInInput = new Set<string>();
     for (const result of input.results) {
-      const key = `${result.mirrorHash}:${result.seq}:${result.documentId ?? ""}`;
+      const key = fusionKey(result);
+      if (countedInInput.has(key)) continue;
+      countedInInput.add(key);
       let candidate = candidates.get(key);
 
       if (!candidate) {
@@ -116,8 +128,11 @@ export function rrfFuse(
       weight = config.vecWeight * 0.7;
     }
 
+    const countedInInput = new Set<string>();
     for (const result of input.results) {
-      const key = `${result.mirrorHash}:${result.seq}:${result.documentId ?? ""}`;
+      const key = fusionKey(result);
+      if (countedInInput.has(key)) continue;
+      countedInInput.add(key);
       let candidate = candidates.get(key);
 
       if (!candidate) {
@@ -137,6 +152,8 @@ export function rrfFuse(
 
       // Track best vector rank
       if (candidate.vecRank === null || result.rank < candidate.vecRank) {
+        // The best-ranked chunk represents the document downstream.
+        candidate.seq = result.seq;
         candidate.vecRank = result.rank;
       }
 
@@ -152,8 +169,11 @@ export function rrfFuse(
   for (const input of graphInputs) {
     const weight = config.bm25Weight * 0.8;
 
+    const countedInInput = new Set<string>();
     for (const result of input.results) {
-      const key = `${result.mirrorHash}:${result.seq}:${result.documentId ?? ""}`;
+      const key = fusionKey(result);
+      if (countedInInput.has(key)) continue;
+      countedInInput.add(key);
       let candidate = candidates.get(key);
 
       if (!candidate) {

package/src/pipeline/hybrid.ts

@@ -73,7 +73,10 @@ import {
   summarizeQueryModes,
 } from "./query-modes";
 import { rerankCandidates } from "./rerank";
-import { attachSearchResultContexts } from "./result-context";
+import {
+  attachSearchResultContexts,
+  attachSupersession,
+} from "./result-context";
 import { cleanDisplaySnippet } from "./snippet";
 import {
   isWithinTemporalRange,
@@ -1364,6 +1367,7 @@ async function searchHybridWithHydration(
       }
     : undefined;
   await attachSearchResultContexts(store, finalResults);
+  await attachSupersession(store, finalResults);
   const lineageResult = await attachSearchResultEgressLineage(
     store,
     finalResults,

package/src/pipeline/query-snippet.ts

@@ -0,0 +1,266 @@
+/**
+ * BM25 result snippets built from stored chunks.
+ *
+ * FTS5 `snippet()` re-tokenizes the whole body of every matched document
+ * before LIMIT, which made long questions take seconds. Snippets are built
+ * for the returned rows only: pick the chunk that best covers the query terms
+ * (terms weighted by rarity across the returned chunks, so a chunk with
+ * "ladder" beats one with only "the" and "does"; lowest seq on ties), then
+ * its best 32-token window, with matching tokens wrapped in `<mark>`/`</mark>`
+ * and `...` where the window cuts the chunk, as `snippet()` did. Chunk choice
+ * uses substring presence of lightly stemmed terms; highlighting uses word
+ * prefixes. Both approximate the index tokenizer and affect display only,
+ * never ranking.
+ *
+ * @module src/pipeline/query-snippet
+ */
+
+/** Tokens per snippet window (the old `snippet(..., 32)` budget). */
+const WINDOW_TOKENS = 32;
+
+/** Repeat hits only break ties between windows with equal term coverage. */
+const HIT_TIEBREAK = 1e-6;
+
+const TOKEN_REGEX = /[\p{L}\p{N}\p{M}]+/gu;
+
+/** Quoted phrase (optionally negated) or a bare token, as the lexical grammar splits them. */
+const QUERY_PART_REGEX = /(-?)"([^"]*)"|(\S+)/g;
+
+const DIACRITIC_REGEX = /\p{M}/gu;
+
+const NON_ASCII_REGEX = /[^\p{ASCII}]/u;
+
+/** Final doubled consonant left by suffix removal (`embedd` -> `embed`). */
+const DOUBLED_CONSONANT_REGEX = /([bdfgkmnprt])\1$/;
+
+/** Suffixes removed from query terms, longest first. */
+const STEM_SUFFIXES = [
+  "ational",
+  "ations",
+  "ation",
+  "ings",
+  "ions",
+  "ers",
+  "ied",
+  "ies",
+  "ing",
+  "ion",
+  "al",
+  "ed",
+  "er",
+  "ly",
+  "e",
+  "s",
+  "y",
+];
+
+const MIN_STEM_LENGTH = 3;
+
+export interface SnippetTerms {
+  /** Lowercase term prefixes (stemmed query words and diacritic-free forms). */
+  prefixes: string[];
+  /** Query word id per prefix; variants of one word share an id. */
+  ids: number[];
+  /** Anchored prefix matcher for one lowercased token. */
+  token: RegExp;
+  idByPrefix: Map<string, number>;
+}
+
+/** Query word ids present in one chunk. */
+export interface ChunkTermSet {
+  seq: number;
+  terms: Set<number>;
+}
+
+interface Token {
+  start: number;
+  end: number;
+  term: number;
+}
+
+const stripDiacritics = (text: string): string =>
+  NON_ASCII_REGEX.test(text)
+    ? text.normalize("NFD").replace(DIACRITIC_REGEX, "")
+    : text;
+
+function stemPrefix(term: string): string {
+  if (term.length <= MIN_STEM_LENGTH) return term;
+  for (const suffix of STEM_SUFFIXES) {
+    if (
+      term.endsWith(suffix) &&
+      term.length - suffix.length >= MIN_STEM_LENGTH
+    ) {
+      const stem = term.slice(0, -suffix.length);
+      return DOUBLED_CONSONANT_REGEX.test(stem) ? stem.slice(0, -1) : stem;
+    }
+  }
+  return term;
+}
+
+/** Positive terms of a lexical query; null when there are none. */
+export function createSnippetTerms(query: string): SnippetTerms | null {
+  const idByPrefix = new Map<string, number>();
+  let nextId = 0;
+  for (const part of query.matchAll(QUERY_PART_REGEX)) {
+    const bare = part[3];
+    if (part[1] === "-" || bare?.startsWith("-")) continue;
+    for (const [word] of (part[2] ?? bare ?? "").matchAll(TOKEN_REGEX)) {
+      const lower = word.toLowerCase();
+      for (const form of new Set([lower, stripDiacritics(lower)])) {
+        const prefix = stemPrefix(form);
+        if (!idByPrefix.has(prefix)) idByPrefix.set(prefix, nextId);
+      }
+      nextId += 1;
+    }
+  }
+  if (idByPrefix.size === 0) return null;
+  const prefixes = [...idByPrefix.keys()].sort((a, b) => b.length - a.length);
+  return {
+    prefixes,
+    ids: prefixes.map((prefix) => idByPrefix.get(prefix) ?? -1),
+    token: new RegExp(`^(?:${prefixes.join("|")})`, "u"),
+    idByPrefix,
+  };
+}
+
+/** In-memory equivalent of the store's chunk term presence query. */
+export function chunkTermPresence(
+  text: string,
+  terms: SnippetTerms
+): boolean[] {
+  const lower = text.toLowerCase();
+  return terms.prefixes.map((prefix) => lower.includes(prefix));
+}
+
+export function presentTermIds(
+  present: boolean[],
+  terms: SnippetTerms
+): Set<number> {
+  const ids = new Set<number>();
+  for (const [index, flag] of present.entries()) {
+    const id = terms.ids[index];
+    if (flag && id !== undefined) ids.add(id);
+  }
+  return ids;
+}
+
+/** Rarity weight per query word across all candidate chunks. */
+export function snippetTermWeights(
+  chunks: Iterable<ChunkTermSet>
+): Map<number, number> {
+  let total = 0;
+  const frequency = new Map<number, number>();
+  for (const { terms } of chunks) {
+    total += 1;
+    for (const term of terms)
+      frequency.set(term, (frequency.get(term) ?? 0) + 1);
+  }
+  const weights = new Map<number, number>();
+  for (const [term, count] of frequency)
+    weights.set(term, Math.log(1 + total / count));
+  return weights;
+}
+
+/** Seq of the chunk with the best weighted coverage (lowest seq on ties). */
+export function pickSnippetSeq(
+  chunks: ChunkTermSet[],
+  weights: Map<number, number>
+): number | undefined {
+  let best: ChunkTermSet | undefined;
+  let bestScore = -1;
+  for (const chunk of chunks) {
+    let score = 0;
+    for (const term of chunk.terms) score += weights.get(term) ?? 0;
+    if (
+      score > bestScore ||
+      (score === bestScore && best && chunk.seq < best.seq)
+    ) {
+      bestScore = score;
+      best = chunk;
+    }
+  }
+  return best?.seq;
+}
+
+function tokenize(text: string, terms: SnippetTerms): Token[] {
+  const tokens: Token[] = [];
+  for (const match of text.matchAll(TOKEN_REGEX)) {
+    const start = match.index;
+    const word = match[0];
+    const prefix = terms.token.exec(stripDiacritics(word.toLowerCase()));
+    tokens.push({
+      start,
+      end: start + word.length,
+      term: prefix ? (terms.idByPrefix.get(prefix[0]) ?? -1) : -1,
+    });
+  }
+  return tokens;
+}
+
+/** Start index of the window with the best weighted term coverage. */
+function bestWindowStart(
+  tokens: Token[],
+  weights: Map<number, number>
+): number {
+  if (tokens.length <= WINDOW_TOKENS) return 0;
+  const counts = new Map<number, number>();
+  let covered = 0;
+  let hits = 0;
+  const add = (term: number, delta: number) => {
+    if (term < 0) return;
+    const count = (counts.get(term) ?? 0) + delta;
+    counts.set(term, count);
+    hits += delta;
+    const weight = weights.get(term) ?? 1;
+    if (delta > 0 && count === 1) covered += weight;
+    if (delta < 0 && count === 0) covered -= weight;
+  };
+  let bestStart = 0;
+  let bestScore = -1;
+  for (let index = 0; index < tokens.length; index += 1) {
+    add(tokens[index]?.term ?? -1, 1);
+    const start = index - WINDOW_TOKENS + 1;
+    if (start > 0) add(tokens[start - 1]?.term ?? -1, -1);
+    if (start < 0) continue;
+    const score = covered + hits * HIT_TIEBREAK;
+    if (score > bestScore) {
+      bestScore = score;
+      bestStart = start;
+    }
+  }
+  // Center the hits inside the chosen window.
+  let first = -1;
+  let last = -1;
+  for (let index = bestStart; index < bestStart + WINDOW_TOKENS; index += 1) {
+    if ((tokens[index]?.term ?? -1) < 0) continue;
+    if (first < 0) first = index;
+    last = index;
+  }
+  if (first < 0) return bestStart;
+  const centered = first - Math.floor((WINDOW_TOKENS - (last - first + 1)) / 2);
+  return Math.max(0, Math.min(centered, tokens.length - WINDOW_TOKENS));
+}
+
+/** The best 32-token window of one chunk, query terms in `<mark>` tags. */
+export function renderChunkSnippet(
+  text: string,
+  terms: SnippetTerms,
+  weights: Map<number, number>
+): string {
+  const tokens = tokenize(text, terms);
+  if (tokens.length === 0) return text;
+  const start = bestWindowStart(tokens, weights);
+  const end = Math.min(tokens.length, start + WINDOW_TOKENS) - 1;
+  const atStart = start === 0;
+  const atEnd = end === tokens.length - 1;
+  let cursor = atStart ? 0 : (tokens[start]?.start ?? 0);
+  let out = atStart ? "" : "...";
+  for (let index = start; index <= end; index += 1) {
+    const token = tokens[index];
+    if (!token || token.term < 0) continue;
+    out += `${text.slice(cursor, token.start)}<mark>${text.slice(token.start, token.end)}</mark>`;
+    cursor = token.end;
+  }
+  out += text.slice(cursor, atEnd ? text.length : (tokens[end]?.end ?? 0));
+  return atEnd ? out : `${out}...`;
+}

package/src/pipeline/result-context.ts

@@ -57,3 +57,32 @@ export async function attachSearchResultContexts(
     // the historical result shape and are reported by config validation.
   }
 }
+
+/**
+ * Mark results whose memory fact a newer fact superseded, naming the current
+ * successor. Fail-open like context guidance: a lookup failure marks nothing.
+ */
+export async function attachSupersession(
+  store: StorePort,
+  results: { uri: string; supersededBy?: string }[]
+): Promise<void> {
+  if (results.length === 0 || !store.getSupersedingUris) return;
+  const successors = await store.getSupersedingUris(
+    results.map((result) => result.uri)
+  );
+  if (!successors.ok) return;
+  for (const result of results) {
+    const successor = successors.value.get(result.uri);
+    if (successor) result.supersededBy = successor;
+  }
+}
+
+/** Current successor URI of one document's superseded memory fact, if any. */
+export async function supersedingUri(
+  store: StorePort,
+  uri: string
+): Promise<string | undefined> {
+  if (!store.getSupersedingUris) return undefined;
+  const successors = await store.getSupersedingUris([uri]);
+  return successors.ok ? successors.value.get(uri) : undefined;
+}

package/src/pipeline/search.ts

@@ -8,6 +8,7 @@
 import { join as pathJoin } from "node:path"; // No Bun path utils equivalent
 
 import type { ChunkRow, FtsResult, StorePort } from "../store/types";
+import type { ChunkTermSet, SnippetTerms } from "./query-snippet";
 import type {
   SearchOptions,
   SearchResult,
@@ -31,7 +32,18 @@ import { typedMetadataWarnings } from "./filters";
 import { selectBestChunkForSteering } from "./intent";
 import { hasProjectAffinity } from "./project-affinity";
 import { detectQueryLanguage } from "./query-language";
-import { attachSearchResultContexts } from "./result-context";
+import {
+  chunkTermPresence,
+  createSnippetTerms,
+  pickSnippetSeq,
+  presentTermIds,
+  renderChunkSnippet,
+  snippetTermWeights,
+} from "./query-snippet";
+import {
+  attachSearchResultContexts,
+  attachSupersession,
+} from "./result-context";
 import { cleanDisplaySnippet } from "./snippet";
 import {
   resolveRecencyTimestamp,
@@ -41,6 +53,9 @@ import {
 import { attachSearchResultPlannerMetadata } from "./trace-metadata";
 import { SEARCH_RESULT_PLANNER_METADATA } from "./types";
 
+const passageHash = (text: string): string =>
+  new Bun.CryptoHasher("sha256").update(text).digest("hex");
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Score Normalization
 // ─────────────────────────────────────────────────────────────────────────────
@@ -121,11 +136,9 @@ function buildSearchResult(ctx: BuildResultContext): SearchResult {
     snippet = chunk.text;
     snippetRange = { startLine: chunk.startLine, endLine: chunk.endLine };
   } else {
-    // Default: FTS snippet or chunk text, with leading frontmatter stripped
-    const cleaned = cleanDisplaySnippet(
-      fts.snippet ?? chunk?.text ?? "",
-      chunk?.text
-    );
+    // Default: chunk text until attachChunkSnippets replaces it for the final
+    // rows, with leading frontmatter stripped
+    const cleaned = cleanDisplaySnippet(chunk?.text ?? "", chunk?.text);
     snippet = cleaned.text;
     if (chunk) {
       line = chunk.startLine + cleaned.startLineOffset;
@@ -159,12 +172,132 @@ function buildSearchResult(ctx: BuildResultContext): SearchResult {
     graphExpanded: false,
     startLine: chunk.startLine,
     endLine: chunk.endLine,
-    passageHash: new Bun.CryptoHasher("sha256")
-      .update(chunk.text)
-      .digest("hex"),
+    passageHash: passageHash(chunk.text),
   });
 }
 
+/** Query-word ids present in each chunk of the returned documents. */
+async function readChunkTermSets(
+  store: StorePort,
+  hashes: string[],
+  terms: SnippetTerms,
+  loadedChunks: Map<string, ChunkRow[]> | undefined
+): Promise<{
+  termSets: Map<string, ChunkTermSet[]>;
+  chunks?: Map<string, ChunkRow[]>;
+} | null> {
+  const termSets = new Map<string, ChunkTermSet[]>();
+  const add = (mirrorHash: string, seq: number, present: boolean[]) => {
+    const list = termSets.get(mirrorHash) ?? [];
+    list.push({ seq, terms: presentTermIds(present, terms) });
+    termSets.set(mirrorHash, list);
+  };
+  // In-database presence keeps long documents from being loaded whole.
+  const presence =
+    !loadedChunks && store.getChunkTermPresence
+      ? await store.getChunkTermPresence(hashes, terms.prefixes)
+      : undefined;
+  if (presence?.ok) {
+    for (const row of presence.value) add(row.mirrorHash, row.seq, row.present);
+    return { termSets };
+  }
+  let chunks = loadedChunks;
+  if (!chunks) {
+    const fetched = await store.getChunksBatch(hashes);
+    if (!fetched.ok) return null;
+    chunks = fetched.value;
+  }
+  for (const [mirrorHash, list] of chunks)
+    for (const chunk of list)
+      add(mirrorHash, chunk.seq, chunkTermPresence(chunk.text, terms));
+  return { termSets, chunks };
+}
+
+/**
+ * Default-mode snippets for the returned rows only, built from their stored
+ * chunks (FTS5 snippet() re-tokenized every matched document body). Only the
+ * chosen chunk of each row is loaded; with an intent, the steered chunk is
+ * kept. The snippet, its range and the planner chunk all name that chunk.
+ * Updates results in place so hidden ranking metadata stays attached.
+ */
+async function attachChunkSnippets(
+  store: StorePort,
+  results: SearchResult[],
+  query: string,
+  options: SearchOptions,
+  loadedChunks: Map<string, ChunkRow[]> | undefined
+): Promise<void> {
+  const terms = createSnippetTerms(query);
+  const hashes = [
+    ...new Set(
+      results
+        .map((result) => result.conversion?.mirrorHash)
+        .filter((hash): hash is string => Boolean(hash))
+    ),
+  ];
+  if (!terms || hashes.length === 0) return;
+  const read = await readChunkTermSets(store, hashes, terms, loadedChunks);
+  if (!read) return;
+  const weights = snippetTermWeights([...read.termSets.values()].flat());
+
+  const chosen = results.map((result) => {
+    const mirrorHash = result.conversion?.mirrorHash;
+    if (!mirrorHash) return undefined;
+    const steeredSeq = result[SEARCH_RESULT_PLANNER_METADATA]?.seq;
+    const candidates = read.termSets.get(mirrorHash) ?? [];
+    const seq = pickSnippetSeq(
+      options.intent
+        ? candidates.filter((entry) => entry.seq === steeredSeq)
+        : candidates,
+      weights
+    );
+    return seq === undefined ? undefined : { mirrorHash, seq };
+  });
+  let chunks = read.chunks;
+  if (!chunks) {
+    const fetched = store.getChunksBySequenceBatch
+      ? await store.getChunksBySequenceBatch(
+          chosen.filter((key) => key !== undefined)
+        )
+      : await store.getChunksBatch(hashes);
+    if (!fetched.ok) return;
+    chunks = fetched.value;
+  }
+  const getChunk = createChunkLookup(chunks);
+
+  for (const [index, result] of results.entries()) {
+    const key = chosen[index];
+    const chunk = key ? getChunk(key.mirrorHash, key.seq) : undefined;
+    if (!(key && chunk)) continue;
+    const cleaned = cleanDisplaySnippet(
+      renderChunkSnippet(chunk.text, terms, weights),
+      chunk.text
+    );
+    result.line = chunk.startLine + cleaned.startLineOffset;
+    result.snippet = cleaned.text;
+    result.snippetLanguage = chunk.language ?? undefined;
+    result.snippetRange = { startLine: result.line, endLine: chunk.endLine };
+    const coordinates = {
+      mirrorHash: key.mirrorHash,
+      seq: chunk.seq,
+      startLine: chunk.startLine,
+      endLine: chunk.endLine,
+      passageHash: passageHash(chunk.text),
+    };
+    const metadata = result[SEARCH_RESULT_PLANNER_METADATA];
+    if (metadata) {
+      Object.assign(metadata, coordinates);
+    } else {
+      attachSearchResultPlannerMetadata(result, {
+        retrievalRank: 0,
+        sources: ["bm25"],
+        graphExpanded: false,
+        ...coordinates,
+      });
+    }
+  }
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Search Function
 // ─────────────────────────────────────────────────────────────────────────────
@@ -204,8 +337,7 @@ export async function searchBm25(
   const detection = detectQueryLanguage(query);
   const queryLanguage = options.lang ?? detection.bcp47;
 
-  // Run FTS search
-  // Disable FTS snippet when --full or --line-numbers (we use raw text instead)
+  // Run FTS search (ranking only; snippets come from chunks of the final rows)
   const ftsResult = await store.searchFts(query, {
     limit: retrievalLimit,
     collection: options.collection,
@@ -213,7 +345,6 @@ export async function searchBm25(
     exclude: options.exclude,
     relPathPrefix: options.retrievalScope?.relPathPrefix,
     language: options.lang,
-    snippet: !(options.full || options.lineNumbers),
     tagsAll: options.tagsAll,
     tagsAny: options.tagsAny,
     since: temporalRange.since,
@@ -262,10 +393,9 @@ export async function searchBm25(
       ftsResult.value.map((f) => f.mirrorHash).filter((h): h is string => !!h)
     ),
   ];
+  const needsAllChunks = Boolean(options.intent || options.exclude?.length);
   const chunksMapResult =
-    store.getChunksBySequenceBatch &&
-    !options.intent &&
-    !options.exclude?.length
+    store.getChunksBySequenceBatch && !needsAllChunks
       ? await store.getChunksBySequenceBatch(
           ftsResult.value
             .filter((row) => !!row.mirrorHash)
@@ -275,6 +405,10 @@ export async function searchBm25(
   const getChunk = chunksMapResult.ok
     ? createChunkLookup(chunksMapResult.value)
     : () => undefined;
+  const allChunks =
+    chunksMapResult.ok && (needsAllChunks || !store.getChunksBySequenceBatch)
+      ? chunksMapResult.value
+      : undefined;
 
   // Dedup: multiple docs can share mirror_hash (content-addressed storage)
   // Track seen uri+seq to eliminate duplicate rows from join fan-out
@@ -323,11 +457,7 @@ export async function searchBm25(
 
     const excluded =
       matchesExcludedText(
-        [
-          fts.title ?? "",
-          fts.recordSourcePath ?? fts.relPath ?? "",
-          fts.snippet ?? "",
-        ],
+        [fts.title ?? "", fts.recordSourcePath ?? fts.relPath ?? ""],
         options.exclude
       ) ||
       matchesExcludedChunks(
@@ -461,11 +591,15 @@ export async function searchBm25(
   }
 
   const finalResults = filteredResults.slice(0, limit);
+  if (!(options.full || options.lineNumbers)) {
+    await attachChunkSnippets(store, finalResults, query, options, allChunks);
+  }
   for (const [index, result] of finalResults.entries()) {
     const metadata = result[SEARCH_RESULT_PLANNER_METADATA];
     if (metadata) metadata.retrievalRank = index + 1;
   }
   await attachSearchResultContexts(store, finalResults);
+  await attachSupersession(store, finalResults);
   const lineageResult = await attachSearchResultEgressLineage(
     store,
     finalResults,

package/src/pipeline/types.ts

@@ -94,6 +94,8 @@ export interface SearchResult {
   record?: RecordEvidenceMetadata;
   /** Complete, most-restrictive collection ownership for this derived result. */
   egressLineage?: EgressLineage;
+  /** URI of the current fact when a newer memory fact superseded this one. */
+  supersededBy?: string;
   [SEARCH_RESULT_PLANNER_METADATA]?: SearchResultPlannerMetadata;
 }
 
@@ -455,6 +457,8 @@ export interface Citation {
   uri: string;
   startLine?: number;
   endLine?: number;
+  /** URI of the current fact when a newer memory fact superseded the cited one. */
+  supersededBy?: string;
   [CITATION_TRACE_METADATA]?: CitationTraceMetadata;
 }
 

package/src/pipeline/vsearch.ts

@@ -38,7 +38,10 @@ import { typedMetadataWarnings, typedMetadataFilterReason } from "./filters";
 import { selectBestChunkForSteering } from "./intent";
 import { hasProjectAffinity } from "./project-affinity";
 import { detectQueryLanguage } from "./query-language";
-import { attachSearchResultContexts } from "./result-context";
+import {
+  attachSearchResultContexts,
+  attachSupersession,
+} from "./result-context";
 import { cleanDisplaySnippet } from "./snippet";
 import {
   resolveRecencyTimestamp,
@@ -520,6 +523,7 @@ async function searchVectorWithEmbeddingOwned(
     if (metadata) metadata.retrievalRank = index + 1;
   }
   await attachSearchResultContexts(store, finalResults);
+  await attachSupersession(store, finalResults);
   const lineageResult = await attachSearchResultEgressLineage(
     store,
     finalResults,