@remnic/core 9.7.14 → 9.8.0

package/src/orchestration/recall-rerank-coordinator.ts

@@ -27,11 +27,13 @@ import {
 import {
   applyTrustScoreStage,
   buildTrustSignalsForRerank,
+  trustResultKey,
   type TrustStageResultItem,
 } from "../trust-score-stage.js";
 import type { TrustSignals } from "../trust-score.js";
 import { reorderRecallResultsWithMmr } from "../recall-mmr.js";
 import { applyReasoningTraceBoost } from "../reasoning-trace-recall.js";
+import { memoryMapKey } from "../recall-memory-map.js";
 
 /**
  * Coordinator for the recall-result reranking subsystem.
@@ -47,19 +49,49 @@ export class RecallRerankCoordinator {
     resultPath: string,
     fallbackStorage: StorageManager,
     recallNamespaces: readonly string[],
+    preferredNamespace?: string,
   ) => Promise<MemoryFile | null>;
 
+  // Per-namespace corpus-fallback caches (issue #1905). Keyed on the shared
+  // cross-process memory-corpus version rather than a wall-clock TTL: the old
+  // 30s TTL was SHORTER than recall p50 (~30.5s) so every steady-state recall
+  // was a guaranteed miss + full-corpus scan. The corpus version bumps on every
+  // memory mutation (StorageManager.getMemoryCorpusVersion / patchHotMemoriesCache),
+  // including mw_success/mw_fail counter writes, so a version match means the
+  // derived map is still current and can be served; a mismatch re-derives.
   private readonly memoryWorthCounterCache = new Map<
     string,
-    { at: number; counters: ReadonlyMap<string, MemoryWorthCounters> }
+    { version: number; counters: ReadonlyMap<string, MemoryWorthCounters> }
   >();
-  private static readonly MEMORY_WORTH_CACHE_TTL_MS = 30_000;
 
   private readonly trustSignalCache = new Map<
     string,
-    { at: number; signals: ReadonlyMap<string, TrustSignals> }
+    { version: number; cachedAt: number; signals: ReadonlyMap<string, TrustSignals> }
   >();
-  private static readonly TRUST_SIGNAL_CACHE_TTL_MS = 30_000;
+
+  /**
+   * Cap on distinct namespaces retained in the corpus-fallback caches. Each
+   * entry holds a derived per-namespace map; on high-cardinality namespace
+   * workloads an unbounded map would grow without limit (#1905, Cursor). Map
+   * preserves insertion order, so overflow evicts the oldest namespace.
+   */
+  private static readonly CORPUS_FALLBACK_CACHE_MAX_NAMESPACES = 64;
+
+  // Trust-signal age bound (TRUST_SIGNAL_CACHE_MAX_AGE_MS) lives in
+  // trust-score-stage.ts — that module owns the signal cache's read/write and
+  // the TTL check (signals bake `now` into their values). This coordinator only
+  // owns the memory-worth counter cache, whose values are raw (no `now`), so it
+  // is version-keyed only.
+
+
+  /** Insert-ordered bounded set: evict the oldest namespace on overflow. */
+  private static capCache<K, V>(cache: Map<K, V>, max: number): void {
+    while (cache.size > max) {
+      const oldest = cache.keys().next().value;
+      if (oldest === undefined) break;
+      cache.delete(oldest);
+    }
+  }
 
   constructor(options: {
     getConfig: () => PluginConfig;
@@ -68,6 +100,7 @@ export class RecallRerankCoordinator {
       resultPath: string,
       fallbackStorage: StorageManager,
       recallNamespaces: readonly string[],
+      preferredNamespace?: string,
     ) => Promise<MemoryFile | null>;
   }) {
     this.getConfig = options.getConfig;
@@ -78,66 +111,110 @@ export class RecallRerankCoordinator {
   async applyMemoryWorthRerank(
     results: QmdSearchResult[],
     namespaces: string[],
+    // Candidate frontmatter already loaded on the hot recall path (issue
+    // #1905). Additive + last so the positional call shape stays
+    // backward-compatible. When present, counters are seeded from it directly
+    // and the O(corpus) `readAllMemories` scan is skipped for warm candidates.
+    preloadedFrontmatter?: ReadonlyMap<string, MemoryFile>,
+    // Cooperative cancellation (issue #1905, Codex); additive + last.
+    abortSignal?: AbortSignal,
   ): Promise<QmdSearchResult[]> {
-    // Build the counter lookup. We union frontmatter counters across every
-    // namespace the recall spans — the recall path itself already
-    // aggregates candidates from multiple namespaces, so we must do the
-    // same when looking up counters. Per-namespace results are cached with
-    // a short TTL so interactive recall doesn't trigger a full
-    // `readAllMemories` scan per query (addresses codex P2 on PR 4).
+    const config = this.getConfig();
     const counters = new Map<string, MemoryWorthCounters>();
-    const seenNamespaces = new Set<string>();
-    const nowMs = Date.now();
+    // Paths examined via preloaded frontmatter (issue #1905, Codex). A candidate
+    // whose frontmatter is present but has no mw_success/mw_fail is a NEUTRAL
+    // prior — it must NOT be treated as "missing", otherwise the corpus scan +
+    // direct-read fallback fire for every uninstrumented hot-QMD candidate and
+    // the O(candidates) fast path is defeated. Track preloaded paths separately
+    // from counters and exclude them from every fallback.
+    const preloadedPaths = new Set<string>();
 
-    // Evict all expired entries on every call so long-running processes
-    // touching a high-cardinality namespace set (coding/project overlays,
-    // per-branch) don't grow the cache unboundedly. Without this, an entry
-    // for a namespace that's never looked up again would pin its full
-    // counter map forever.
-    for (const [key, entry] of this.memoryWorthCounterCache) {
-      if (nowMs - entry.at >= RecallRerankCoordinator.MEMORY_WORTH_CACHE_TTL_MS) {
-        this.memoryWorthCounterCache.delete(key);
+    // O(candidates) fast path (issue #1905): seed counters directly from
+    // frontmatter already loaded on the hot path. The
+    // `mw_success === undefined && mw_fail === undefined` guard matches
+    // `buildMemoryWorthCounterMap` exactly so a candidate with no counters is a
+    // neutral prior, identical to the corpus scan.
+    if (preloadedFrontmatter) {
+      for (const r of results) {
+        const key = memoryMapKey(r);
+        // Composite (namespace, path) key is authoritative — it can never hit a
+        // wrong-namespace entry. The bare-path fallback keeps path-keyed callers
+        // working and is inert in production (loaded maps are composite-keyed).
+        const mem = preloadedFrontmatter.get(key) ?? preloadedFrontmatter.get(r.path);
+        if (!mem) continue;
+        preloadedPaths.add(key);
+        const fm = mem.frontmatter;
+        if (fm.mw_success === undefined && fm.mw_fail === undefined) continue;
+        counters.set(key, {
+          mw_success: fm.mw_success,
+          mw_fail: fm.mw_fail,
+          lastAccessed: fm.lastAccessed,
+        });
       }
     }
 
-    for (const ns of namespaces) {
-      if (seenNamespaces.has(ns)) continue;
-      seenNamespaces.add(ns);
-      try {
-        const cached = this.memoryWorthCounterCache.get(ns);
-        let nsMap: ReadonlyMap<string, MemoryWorthCounters> | undefined;
-        if (
-          cached &&
-          nowMs - cached.at < RecallRerankCoordinator.MEMORY_WORTH_CACHE_TTL_MS
-        ) {
-          nsMap = cached.counters;
-        } else {
+    // Corpus-level fallback (config-gated): candidates still missing from the
+    // preloaded map probe a per-namespace counter map. The map is cached and
+    // invalidated by the shared cross-process corpus version (not a wall-clock
+    // TTL), so it actually hits in steady state. Only the candidate rows are
+    // copied out — never the whole ~99K-entry map (issue #1905).
+    if (config.recallTrustStageCorpusFallbackEnabled) {
+      const seenNamespaces = new Set<string>();
+      for (const ns of namespaces) {
+        // Cooperative cancellation: the recall's assembly deadline may have won
+        // the race — stop before another namespace scan (#1905, Codex).
+        if (abortSignal?.aborted) break;
+        if (seenNamespaces.has(ns)) continue;
+        seenNamespaces.add(ns);
+        if (results.every((r) => counters.has(memoryMapKey(r)) || preloadedPaths.has(memoryMapKey(r)))) break;
+        try {
           const storage = await this.getStorage(ns);
-          const memories = await storage.readAllMemories();
-          nsMap = buildMemoryWorthCounterMap(memories);
-          this.memoryWorthCounterCache.set(ns, { at: nowMs, counters: nsMap });
+          const version = storage.getMemoryCorpusVersion();
+          const cached = this.memoryWorthCounterCache.get(ns);
+          let nsMap: ReadonlyMap<string, MemoryWorthCounters>;
+          if (cached && cached.version === version) {
+            nsMap = cached.counters;
+          } else {
+            const memories = await storage.readAllMemories();
+            nsMap = buildMemoryWorthCounterMap(memories);
+            this.memoryWorthCounterCache.set(ns, { version, counters: nsMap });
+            RecallRerankCoordinator.capCache(
+              this.memoryWorthCounterCache,
+              RecallRerankCoordinator.CORPUS_FALLBACK_CACHE_MAX_NAMESPACES,
+            );
+          }
+          for (const r of results) {
+            // Skip candidates already satisfied by a counter OR already examined
+            // via preloaded frontmatter (neutral prior — no corpus lookup needed).
+            const key = memoryMapKey(r);
+            if (counters.has(key) || preloadedPaths.has(key)) continue;
+            // A namespaced result belongs to exactly one namespace: never seed
+            // its counters from a different namespace's corpus map, or two
+            // same-path results in different namespaces collapse (#2020).
+            if (r.namespace !== undefined && r.namespace !== ns) continue;
+            const c = nsMap.get(r.path);
+            if (c) counters.set(key, c);
+          }
+        } catch (err) {
+          log.debug("memory-worth: failed to read namespace, skipping", {
+            namespace: ns,
+            error: (err as Error).message,
+          });
         }
-        for (const [path, c] of nsMap) counters.set(path, c);
-      } catch (err) {
-        log.debug("memory-worth: failed to read namespace, skipping", {
-          namespace: ns,
-          error: (err as Error).message,
-        });
       }
     }
 
-    // For candidates whose path didn't show up in any hot-tier namespace
-    // scan (typical of cold-tier / archive fallback), try a direct
-    // per-path read. Without this, cold-tier candidates always stay at
-    // multiplier 1.0 even when they have outcome history. Errors are
-    // swallowed so a single unreadable archive entry can't break the
-    // whole recall.
-    const missing = results.filter((r) => !counters.has(r.path));
+    // For candidates still absent (cold-tier / archive, or corpus fallback
+    // disabled), try a direct per-path read. Bounded-parallel (≤16) to match
+    // loadSearchResultMemoryMap's batch size (issue #1905). Errors are swallowed
+    // so a single unreadable archive entry can't break the whole recall.
+    const missing = results.filter(
+      (r) => !counters.has(memoryMapKey(r)) && !preloadedPaths.has(memoryMapKey(r)),
+    );
     if (missing.length > 0) {
       // Use the first-seen namespace's storage as the reader — all
-      // StorageManagers share the same on-disk format, and
-      // `readMemoryByPath` takes an absolute path so the baseDir doesn't
-      // have to match.
+      // StorageManagers share the same on-disk format, and readMemoryByPath
+      // takes an absolute path so the baseDir doesn't have to match.
       let reader: StorageManager | null = null;
       for (const ns of namespaces) {
         try {
@@ -148,23 +225,36 @@ export class RecallRerankCoordinator {
         }
       }
       if (reader) {
-        for (const r of missing) {
-          try {
-            const memory = await this.readQmdResultMemory(r.path, reader, namespaces);
-            if (!memory) continue;
-            const fm = memory.frontmatter;
-            if (fm.mw_success === undefined && fm.mw_fail === undefined) continue;
-            counters.set(r.path, {
-              mw_success: fm.mw_success,
-              mw_fail: fm.mw_fail,
-              lastAccessed: fm.lastAccessed,
-            });
-          } catch (err) {
-            log.debug("memory-worth: direct path lookup failed", {
-              path: r.path,
-              error: (err as Error).message,
-            });
-          }
+        const readerNn = reader;
+        const BATCH = 16;
+        for (let off = 0; off < missing.length; off += BATCH) {
+          // Cooperative cancellation between batches (#1905, Codex).
+          if (abortSignal?.aborted) break;
+          await Promise.all(
+            missing.slice(off, off + BATCH).map(async (r) => {
+              try {
+                const memory = await this.readQmdResultMemory(
+                  r.path,
+                  readerNn,
+                  namespaces,
+                  r.namespace,
+                );
+                if (!memory) return;
+                const fm = memory.frontmatter;
+                if (fm.mw_success === undefined && fm.mw_fail === undefined) return;
+                counters.set(memoryMapKey(r), {
+                  mw_success: fm.mw_success,
+                  mw_fail: fm.mw_fail,
+                  lastAccessed: fm.lastAccessed,
+                });
+              } catch (err) {
+                log.debug("memory-worth: direct path lookup failed", {
+                  path: r.path,
+                  error: (err as Error).message,
+                });
+              }
+            }),
+          );
         }
       }
     }
@@ -183,12 +273,13 @@ export class RecallRerankCoordinator {
     // multiplier on top. Ties fall back to the stable secondary key in
     // `applyMemoryWorthFilter`.
     const rankedInputs = results.map((r, i) => ({
-      path: r.path,
+      // Composite (namespace, path) identity so same-path results in different
+      // namespaces stay distinct through the filter and reconstruction (#2020).
+      path: memoryMapKey(r),
       // Large positive rank score so multiplier math stays well-scaled and
       // we never hit zero; descending so earlier items rank higher.
       score: results.length - i,
     }));
-    const config = this.getConfig();
     const filtered = applyMemoryWorthFilter(rankedInputs, {
       counters,
       now: new Date(),
@@ -203,7 +294,7 @@ export class RecallRerankCoordinator {
     // we only reorder. Writing the synthetic rank-weighted score back
     // would contaminate downstream logic (telemetry, confidence gates)
     // that expects the original QMD/rerank score semantics.
-    const byPath = new Map(results.map((r) => [r.path, r]));
+    const byPath = new Map(results.map((r) => [memoryMapKey(r), r]));
     const reordered: QmdSearchResult[] = [];
     for (const item of filtered) {
       const original = byPath.get(item.path);
@@ -229,6 +320,14 @@ export class RecallRerankCoordinator {
   async applyTrustScoreRerank(
     results: QmdSearchResult[],
     namespaces: string[],
+    // Candidate frontmatter already loaded on the hot recall path (issue
+    // #1905); additive + last for positional back-compat. Seeds signals
+    // directly so warm candidates skip the O(corpus) namespace scan.
+    preloadedFrontmatter?: ReadonlyMap<string, MemoryFile>,
+    // Cooperative cancellation (issue #1905, Codex): aborted by the host when
+    // the recall's assembly deadline wins the race, so orphaned corpus scans
+    // stop at the next loop boundary. Additive + last for positional back-compat.
+    abortSignal?: AbortSignal,
   ): Promise<{
     results: QmdSearchResult[];
     trustByPath: Map<string, TrustStageResultItem> | null;
@@ -244,11 +343,19 @@ export class RecallRerankCoordinator {
     // candidate (mirrors the memory-worth filter's reader selection).
     let fallbackReader: StorageManager | null = null;
     const signals = await buildTrustSignalsForRerank(
-      results.map((r) => r.path),
+      results.map((r) => ({
+        path: r.path,
+        // Signals are keyed by the SAME composite key the trust stage looks up
+        // (trustResultKey), and preloaded frontmatter by memoryMapKey, so
+        // same-path results in different namespaces stay distinct (#2020).
+        signalKey: trustResultKey(r),
+        lookupKey: memoryMapKey(r),
+        namespace: r.namespace,
+      })),
       namespaces,
       {
         readNamespaceMemories: async (ns) => (await this.getStorage(ns)).readAllMemories(),
-        readMemoryFrontmatter: async (path) => {
+        readMemoryFrontmatter: async (path, preferredNamespace) => {
           if (!fallbackReader) {
             for (const ns of namespaces) {
               try {
@@ -260,23 +367,38 @@ export class RecallRerankCoordinator {
             }
           }
           if (!fallbackReader) return null;
-          const memory = await this.readQmdResultMemory(path, fallbackReader, namespaces);
+          const memory = await this.readQmdResultMemory(
+            path,
+            fallbackReader,
+            namespaces,
+            preferredNamespace,
+          );
           return memory ? memory.frontmatter : null;
         },
+        // Corpus version bumps on every memory mutation (including mw counter
+        // writes) — keys the per-namespace signal cache so it invalidates on
+        // the next write instead of a wall-clock TTL (issue #1905).
+        getNamespaceVersion: async (ns) => (await this.getStorage(ns)).getMemoryCorpusVersion(),
       },
-      { cache: this.trustSignalCache, ttlMs: RecallRerankCoordinator.TRUST_SIGNAL_CACHE_TTL_MS },
+      { cache: this.trustSignalCache },
       now,
       {
         recencyHalfLifeDays: halfLifeDays,
         logDebug: (message, context) => log.debug(message, context),
+        preloadedFrontmatter,
+        corpusFallbackEnabled: config.recallTrustStageCorpusFallbackEnabled,
+        abortSignal,
       },
     );
     if (signals.size === 0) {
       return { results, trustByPath: null };
     }
     // Synthetic monotone-decreasing rank so the multiplier rebias is applied
-    // on top of upstream ordering, not raw QMD scores (see applyMemoryWorthRerank).
-    const rankedInputs = results.map((r, i) => ({ path: r.path, score: results.length - i }));
+    const rankedInputs = results.map((r, i) => ({
+      path: r.path,
+      key: trustResultKey(r),
+      score: results.length - i,
+    }));
     const stage = applyTrustScoreStage(rankedInputs, {
       signals,
       weights: config.trustScoreWeights,
@@ -284,10 +406,22 @@ export class RecallRerankCoordinator {
       maxMultiplier: config.trustScoreMaxMultiplier,
       quarantine: config.trustScoreQuarantine,
     });
-    const trustByPath = new Map(stage.all.map((item) => [item.path, item]));
-    const byPath = new Map(results.map((r) => [r.path, r]));
+    const trustByPath = new Map(
+      stage.all.map((item) => [item.key ?? item.path, item] as const),
+    );
+    const byKey = new Map<string, QmdSearchResult[]>();
+    for (const result of results) {
+      const key = trustResultKey(result);
+      const bucket = byKey.get(key);
+      if (bucket) bucket.push(result);
+      else byKey.set(key, [result]);
+    }
     const admitted = stage.admitted
-      .map((item) => byPath.get(item.path))
+      .map((item) => {
+        const key = item.key ?? item.path;
+        if (item.key !== undefined) return byKey.get(key)?.shift();
+        return results.find((result) => result.path === item.path);
+      })
       .filter((r): r is QmdSearchResult => r !== undefined);
     return { results: admitted, trustByPath };
   }
@@ -307,13 +441,21 @@ export class RecallRerankCoordinator {
     namespaces: string[],
     caps: CapabilitySet,
     label: string,
+    // Candidate frontmatter already loaded on this branch's hot path (issue
+    // #1905); additive + last. Threaded to the active stage so it does
+    // O(candidates) work instead of a full-corpus scan. `undefined` on
+    // branches without a safety-filter map → falls back to corpus/direct-read
+    // (identical lookup result, rule 41 parity).
+    preloadedFrontmatter?: ReadonlyMap<string, MemoryFile>,
+    // Cooperative cancellation (issue #1905, Codex); additive + last.
+    abortSignal?: AbortSignal,
   ): Promise<{
     results: QmdSearchResult[];
     trustByPath: Map<string, TrustStageResultItem> | null;
   }> {
     if (caps.recallTrustScore && results.length > 0) {
       try {
-        return await this.applyTrustScoreRerank(results, namespaces);
+        return await this.applyTrustScoreRerank(results, namespaces, preloadedFrontmatter, abortSignal);
       } catch (err) {
         log.debug(`trust-score stage (${label}) failed open`, {
           error: (err as Error).message,
@@ -321,7 +463,12 @@ export class RecallRerankCoordinator {
       }
     } else if (caps.recallMemoryWorthFilter && results.length > 0) {
       try {
-        const filtered = await this.applyMemoryWorthRerank(results, namespaces);
+        const filtered = await this.applyMemoryWorthRerank(
+          results,
+          namespaces,
+          preloadedFrontmatter,
+          abortSignal,
+        );
         return { results: filtered, trustByPath: null };
       } catch (err) {
         log.debug(`memory-worth filter (${label}) failed open`, {

package/src/orchestration/recall-result-formatter.ts

@@ -18,6 +18,7 @@
  */
 
 import { buildHandleIndexForResults } from "../recall-handles.js";
+import path from "node:path";
 import { renderEpistemicHedge } from "../trust-score.js";
 import { resolveIdentityContinuityCapabilities } from "../capabilities.js";
 import type { StorageManager } from "../index.js";
@@ -28,7 +29,7 @@ import type { HarmonicRetrievalResult } from "../harmonic-retrieval.js";
 import type { VerifiedEpisodeResult } from "../verified-recall.js";
 import type { VerifiedSemanticRuleResult } from "../semantic-rule-verifier.js";
 import type { WorkProductLedgerSearchResult } from "../work-product-ledger.js";
-import type { TrustStageResultItem } from "../trust-score-stage.js";
+import { trustResultFor, type TrustStageResultItem } from "../trust-score-stage.js";
 import type {
   ContinuityIncidentRecord,
   IdentityInjectionMode,
@@ -66,6 +67,53 @@ export function resolveEffectiveIdentityInjectionMode(options: {
   return { mode: options.configuredMode, shouldInject: true };
 }
 
+/**
+ * Render an internal (possibly absolute) result path as a memoryDir-relative
+ * path for display in prompts/citations, so operator-specific filesystem paths
+ * never leak into recall output and citations stay portable across machines
+ * (#2020). Non-absolute or out-of-root paths are returned unchanged.
+ */
+export function displayResultPath(
+  resultPath: string,
+  memoryDir: string,
+  namespace?: string,
+): string {
+  if (!path.isAbsolute(resultPath)) return resultPath;
+  const root = path.resolve(memoryDir);
+  const nsRoot = path.join(root, "namespaces");
+  if (namespace && (resultPath === nsRoot || resultPath.startsWith(nsRoot + path.sep))) {
+    // memoryDir/namespaces/<token>/<rel> -> "<namespace>/<rel>", the exact
+    // form the citation resolver decodes back to the owning namespace.
+    const afterNs = path.relative(nsRoot, resultPath).split(path.sep).slice(1).join("/");
+    if (afterNs) return `${namespace}/${afterNs}`;
+  }
+  const rel = path.relative(root, resultPath);
+  return rel && !rel.startsWith("..") && !path.isAbsolute(rel)
+    ? rel.split(path.sep).join("/")
+    : resultPath;
+}
+
+/**
+ * Return a copy of budget metadata with `includedMemoryPaths` rendered
+ * memoryDir-relative, so recall/last-recall API callers never receive operator
+ * filesystem paths via budget output even though the internal snapshot keeps
+ * absolute paths for tracking/x-ray (#2020). Other fields are unchanged.
+ */
+export function displaySafeBudgetsApplied<
+  T extends {
+    includedMemoryPaths?: string[];
+    includedMemoryNamespaces?: Array<string | undefined>;
+  },
+>(budgetsApplied: T | undefined, memoryDir: string): T | undefined {
+  if (!budgetsApplied?.includedMemoryPaths) return budgetsApplied;
+  return {
+    ...budgetsApplied,
+    includedMemoryPaths: budgetsApplied.includedMemoryPaths.map((p, i) =>
+      displayResultPath(p, memoryDir, budgetsApplied.includedMemoryNamespaces?.[i]),
+    ),
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Coordinator
 // ---------------------------------------------------------------------------
@@ -80,39 +128,32 @@ export class RecallResultFormatter {
 
   // ── QMD results (memory handles + epistemic hedge) ──────────────────────
 
-  formatQmdResults(
+  formatQmdResultEntries(
     title: string,
     results: QmdSearchResult[],
     sessionKey?: string,
     trustByPath?: Map<string, TrustStageResultItem> | null,
-  ): string {
-    // Issue #1582 — handles are only rendered when a session key is available:
-    // resolution requires the handle history to have been recorded for this
-    // session, which only happens when sessionKey is present. Rendering handles
-    // without recording would show tokens a user can never resolve (cursor
-    // review). The rendering logic itself lives in the pure handles module.
+  ): { heading: string; entries: string[] } {
     const handleByIndex = buildHandleIndexForResults(
       results,
       this.config.recallMemoryHandles === true && sessionKey != null,
     );
-    // Issue #1577 — epistemic hedge. Append a deterministic, component-derived
-    // suffix so the downstream model knows each memory's trust status (the
-    // cheap lever against confident-stale-answer failures). Gated separately
-    // from scoring so rendering can ship after the stage is stable. High-band
-    // and neutral items get no suffix (don't waste tokens on the common case).
-    const renderHedge = this.config.trustScoreEpistemicRendering && trustByPath !== null && trustByPath !== undefined;
+    const renderHedge =
+      this.config.trustScoreEpistemicRendering &&
+      trustByPath !== null &&
+      trustByPath !== undefined;
     const hedgeMap = renderHedge ? trustByPath : null;
-    const lines = results.map((r, i) => {
+    const entries = results.map((r, i) => {
       const snippet = r.snippet
         ? r.snippet.slice(0, 500).replace(/\n/g, " ")
         : "(no preview)";
-      const source = typeof r.line === "number" ? `${r.path}:${r.line}` : r.path;
+      const displayPath = displayResultPath(r.path, this.config.memoryDir, r.namespace);
+      const source = typeof r.line === "number" ? `${displayPath}:${r.line}` : displayPath;
       const head = `[${i + 1}] ${source} (score: ${r.score.toFixed(3)})\n${snippet}`;
       const handle = handleByIndex.get(i);
-      const hedged = head.replace(/\s+$/, "");
-      const withHandle = handle ? `${hedged} ${handle}` : hedged;
+      const withHandle = handle ? `${head.trimEnd()} ${handle}` : head.trimEnd();
       if (hedgeMap) {
-        const item = hedgeMap.get(r.path);
+        const item = trustResultFor(hedgeMap, r);
         if (item) {
           const hedge = renderEpistemicHedge(item.trust);
           if (hedge.length > 0) return `${withHandle} ${hedge}`;
@@ -120,7 +161,22 @@ export class RecallResultFormatter {
       }
       return withHandle;
     });
-    return `## ${title}\n\n${lines.join("\n\n")}`;
+    return { heading: `## ${title}`, entries };
+  }
+
+  formatQmdResults(
+    title: string,
+    results: QmdSearchResult[],
+    sessionKey?: string,
+    trustByPath?: Map<string, TrustStageResultItem> | null,
+  ): string {
+    const formatted = this.formatQmdResultEntries(
+      title,
+      results,
+      sessionKey,
+      trustByPath,
+    );
+    return [formatted.heading, ...formatted.entries].join("\n\n");
   }
 
   // ── Specialized recall result formatters ────────────────────────────────