akm-cli 0.7.5 → 0.8.0-rc1

package/dist/core/time.js

@@ -0,0 +1,51 @@
+/**
+ * Shared time and date utilities.
+ *
+ * Centralises parsing of user-facing `--since` values so that all consumers
+ * interpret the same set of formats (ISO-8601, epoch ms, plain date strings)
+ * consistently without private re-implementations drifting apart.
+ */
+import { UsageError } from "./errors";
+// ── Since-flag parsing ───────────────────────────────────────────────────────
+/**
+ * Parse a user-supplied `--since` value and return an ISO-8601 timestamp
+ * string (e.g. `"2026-01-15T10:30:00.000Z"`).
+ *
+ * Accepted input formats:
+ *   - ISO-8601 timestamp (preferred): `"2026-04-01T00:00:00Z"`
+ *   - Plain date: `"2026-04-01"` (interpreted as start-of-day UTC)
+ *   - Epoch milliseconds (pure digit string): `"1744329600000"`
+ *   - Any other value parseable by `new Date()`
+ *
+ * Callers that need a different wire format (e.g. SQLite `"YYYY-MM-DD HH:MM:SS"`)
+ * should convert the returned ISO string themselves.
+ *
+ * @throws {UsageError} when `since` is empty or cannot be parsed as a date.
+ */
+export function parseSinceToIso(since) {
+    const trimmed = since.trim();
+    if (!trimmed) {
+        throw new UsageError("--since cannot be empty.", "INVALID_FLAG_VALUE");
+    }
+    // Pure-digit input → epoch milliseconds
+    if (/^\d+$/.test(trimmed)) {
+        const ms = Number.parseInt(trimmed, 10);
+        const d = new Date(ms);
+        if (Number.isNaN(d.getTime())) {
+            throw new UsageError(`Invalid --since value: ${since}`, "INVALID_FLAG_VALUE");
+        }
+        return d.toISOString();
+    }
+    const parsed = new Date(trimmed);
+    if (Number.isNaN(parsed.getTime())) {
+        throw new UsageError(`Invalid --since value: ${since}. Expected ISO timestamp (e.g. 2026-04-01T00:00:00Z) or epoch ms.`, "INVALID_FLAG_VALUE");
+    }
+    return parsed.toISOString();
+}
+/**
+ * Convert an ISO-8601 timestamp string to the SQLite datetime format
+ * `"YYYY-MM-DD HH:MM:SS"` used by `datetime('now')`.
+ */
+export function isoToSqlite(iso) {
+    return iso.replace("T", " ").replace(/\.\d+Z$/, "");
+}

package/dist/core/warn.js

@@ -1,12 +1,19 @@
 /**
- * Module-level quiet/verbose flags for stderr warning gating.
+ * Module-level quiet/verbose flags and optional file sink for stderr output.
  *
  * `quiet` is controlled by the CLI `--quiet`/`-q` flag.
  * `verbose` is controlled by the CLI `--verbose` flag, with `AKM_VERBOSE`
  * (env var) winning regardless: env > flag > default (false).
+ *
+ * Call `setLogFile(path)` to tee all warn/error/info output to a file in
+ * addition to stderr. The file sink is written even when `--quiet` suppresses
+ * console output, so logs remain available for post-run inspection.
  */
+import fs from "node:fs";
+import path from "node:path";
 let quiet = false;
 let verbose = false;
+let logFilePath;
 export function setQuiet(value) {
     quiet = value;
 }
@@ -51,15 +58,66 @@ export function isVerbose() {
         return false;
     return verbose;
 }
+/**
+ * Direct all warn/error/info output to `filePath` in addition to stderr.
+ * The directory is created if it does not exist. Pass `undefined` to disable.
+ * The file is written even when `--quiet` suppresses console output.
+ */
+export function setLogFile(filePath) {
+    logFilePath = filePath;
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+export function clearLogFile() {
+    logFilePath = undefined;
+}
+export function getLogFile() {
+    return logFilePath;
+}
+function appendToLogFile(level, args) {
+    if (!logFilePath)
+        return;
+    const ts = new Date().toISOString();
+    const msg = args.map((a) => (typeof a === "string" ? a : JSON.stringify(a))).join(" ");
+    try {
+        fs.appendFileSync(logFilePath, `[${ts}] [${level}] ${msg}\n`);
+    }
+    catch {
+        // Never throw from a logging function — log failures are silent.
+    }
+}
+/**
+ * Emit an info/progress line to stderr unless --quiet is active.
+ * Always written to the log file if one is active.
+ * Use for progress counters and status lines (replaces console.error used for progress).
+ */
+export function info(...args) {
+    appendToLogFile("INFO", args);
+    if (!quiet) {
+        console.warn(...args);
+    }
+}
 /**
  * Emit a warning to stderr unless --quiet is active.
+ * Always written to the log file if one is active.
  * Drop-in replacement for console.warn() across the codebase.
  */
 export function warn(...args) {
+    appendToLogFile("WARN", args);
     if (!quiet) {
         console.warn(...args);
     }
 }
+/**
+ * Emit an error to stderr unless --quiet is active.
+ * Always written to the log file if one is active.
+ * Drop-in replacement for console.error() used for diagnostic failures.
+ */
+export function error(...args) {
+    appendToLogFile("ERROR", args);
+    if (!quiet) {
+        console.error(...args);
+    }
+}
 /**
  * Emit a warning only when verbose output is requested. Use for noisy
  * per-item diagnostics that should be replaced by a one-line summary at

package/dist/indexer/db-search.js

@@ -11,24 +11,21 @@
  * implementation, not a "local vs. remote" distinction.
  */
 import fs from "node:fs";
+import { buildActionFromContributors, defaultActionContributors } from "../core/action-contributors";
 import { makeAssetRef } from "../core/asset-ref";
 import { defaultRendererRegistry } from "../core/asset-registry";
 import { getDbPath } from "../core/paths";
 import { warn } from "../core/warn";
-import { closeDatabase, getAllEntries, getEntryById, getEntryCount, getMeta, getUtilityScoresByIds, openExistingDatabase, sanitizeFtsQuery, searchFts, searchVec, } from "./db";
+import { closeDatabase, getAllEntries, getEntryById, getEntryCount, getMeta, openExistingDatabase, sanitizeFtsQuery, searchFts, searchVec, } from "./db";
 import { ensureIndex } from "./ensure-index";
-import { getRenderer } from "./file-context";
-import { computeGraphBoost, loadGraphBoostContext } from "./graph-boost";
+import { collectGraphRelatedHit, loadGraphBoostContext } from "./graph-boost";
 import { isProposedQuality } from "./metadata";
+import { applyRankingRules, combineSearchScores, normalizeFtsScores } from "./ranking";
+import { enrichSearchHit } from "./search-hit-enrichers";
 import { buildEditHint, findSourceForPath, isEditable } from "./search-source";
 import { deriveSemanticProviderFingerprint, getEffectiveSemanticStatus, isSemanticRuntimeReady, readSemanticStatus, } from "./semantic-status";
-export async function rendererForType(type, registry = defaultRendererRegistry) {
-    const name = registry.rendererNameFor(type);
-    return name ? getRenderer(name) : undefined;
-}
 export function buildLocalAction(type, ref, registry = defaultRendererRegistry) {
-    const builder = registry.actionBuilderFor(type);
-    return builder ? builder(ref) : `akm show ${ref}`;
+    return buildActionFromContributors({ type, ref }, defaultActionContributors(registry)) ?? `akm show ${ref}`;
 }
 function resolveSearchHitRef(entry, refName, source) {
     if (source?.wikiName) {
@@ -44,6 +41,7 @@ export async function searchLocal(input) {
     const { query, searchType, limit, stashDir, sources, config } = input;
     const filters = input.filters;
     const includeProposed = input.includeProposed === true;
+    const beliefFilter = input.beliefFilter ?? "all";
     const rendererRegistry = input.rendererRegistry ?? defaultRendererRegistry;
     const allSourceDirs = sources.map((s) => s.path);
     const rawStatus = readSemanticStatus();
@@ -69,6 +67,7 @@ export async function searchLocal(input) {
             hits: [],
             tip: "No search index available. Run 'akm index' to build one.",
             warnings: warnings.length > 0 ? warnings : undefined,
+            mode: "keyword",
         };
     }
     const db = openExistingDatabase(dbPath);
@@ -79,9 +78,10 @@ export async function searchLocal(input) {
                 hits: [],
                 tip: "Index is empty. Run 'akm index' to populate it.",
                 warnings: warnings.length > 0 ? warnings : undefined,
+                mode: "keyword",
             };
         }
-        const { hits, embedMs, rankMs } = await searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry, filters, includeProposed);
+        const { hits, embedMs, rankMs } = await searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry, filters, includeProposed, beliefFilter);
         return {
             hits,
             tip: hits.length === 0
@@ -90,6 +90,7 @@ export async function searchLocal(input) {
             warnings: warnings.length > 0 ? warnings : undefined,
             embedMs,
             rankMs,
+            mode: embedMs !== undefined && embedMs > 0 ? "semantic" : "keyword",
         };
     }
     finally {
@@ -97,7 +98,7 @@ export async function searchLocal(input) {
     }
 }
 // ── Database search ─────────────────────────────────────────────────────────
-async function searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry = defaultRendererRegistry, filters, includeProposed = false) {
+async function searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry = defaultRendererRegistry, filters, includeProposed = false, beliefFilter = "all") {
     const hasSearchableTokens = query.length > 0 && sanitizeFtsQuery(query).length > 0;
     // Empty queries — including ones that sanitize down to no searchable FTS
     // tokens such as "." — should enumerate matching entries instead of
@@ -124,7 +125,8 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
         const qualityFiltered = includeProposed
             ? scopeFiltered
             : scopeFiltered.filter((ie) => !isProposedQuality(ie.entry.quality));
-        const selected = qualityFiltered.slice(0, limit);
+        const beliefFiltered = qualityFiltered.filter((ie) => matchBeliefFilter(ie.entry.type, ie.entry.beliefState, beliefFilter));
+        const selected = beliefFiltered.slice(0, limit);
         const hits = await Promise.all(selected.map((ie) => buildDbHit({
             entry: ie.entry,
             path: ie.filePath,
@@ -151,22 +153,7 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
     // ── Score normalization ──────────────────────────────────────────────
     // Normalized BM25 + cosine similarity with weighted addition
     // (FTS 0.7, vector 0.3) for well-differentiated combined scores.
-    // Normalize FTS BM25 scores to 0-1 range
-    const ftsScoreMap = new Map();
-    if (ftsResults.length > 0) {
-        // BM25 scores are negative; most negative = best match
-        const bestBm25 = ftsResults[0].bm25Score; // most negative (best)
-        const worstBm25 = ftsResults[ftsResults.length - 1].bm25Score; // least negative (worst)
-        const range = bestBm25 - worstBm25; // negative range
-        for (const r of ftsResults) {
-            // Normalize: best match = 1.0, worst match approaches 0
-            // When range is 0 (all same score), all get 1.0
-            const normalized = range !== 0 ? (r.bm25Score - worstBm25) / range : 1.0;
-            // Scale to 0.3-1.0 range so even the worst FTS hit has a meaningful base score
-            const ftsScore = 0.3 + normalized * 0.7;
-            ftsScoreMap.set(r.id, { score: ftsScore, result: r });
-        }
-    }
+    const ftsScoreMap = normalizeFtsScores(ftsResults);
     // Build embedding score map (cosine similarities already 0-1)
     const embedScoreMap = new Map();
     if (embeddingScores) {
@@ -175,46 +162,12 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
         }
     }
     // ── Combine FTS + vector scores ──────────────────────────────────────
-    const FTS_WEIGHT = 0.7;
-    const VEC_WEIGHT = 0.3;
-    const MAX_BOOST_SUM = 3.0;
-    const scored = [];
-    const seenIds = new Set();
-    // Process FTS results
-    for (const [id, { score: ftsScore, result }] of ftsScoreMap) {
-        seenIds.add(id);
-        const embedScore = embedScoreMap.get(id);
-        let combinedScore;
-        let rankingMode;
-        if (embedScore !== undefined) {
-            combinedScore = ftsScore * FTS_WEIGHT + embedScore * VEC_WEIGHT;
-            rankingMode = "hybrid";
-        }
-        else {
-            combinedScore = ftsScore;
-            rankingMode = "fts";
-        }
-        scored.push({ id, entry: result.entry, filePath: result.filePath, score: combinedScore, rankingMode });
-    }
-    // Add vec-only results not already in FTS results
-    if (embeddingScores) {
-        for (const [id, cosine] of embeddingScores) {
-            if (seenIds.has(id))
-                continue;
-            const found = getEntryById(db, id);
-            if (found) {
-                if (typeFilter && found.entry.type !== typeFilter)
-                    continue;
-                scored.push({
-                    id,
-                    entry: found.entry,
-                    filePath: found.filePath,
-                    score: cosine * VEC_WEIGHT, // Only vector score, no FTS
-                    rankingMode: "semantic",
-                });
-            }
-        }
-    }
+    const scored = combineSearchScores({
+        ftsScoreMap,
+        embedScoreMap,
+        getEntryById: (id) => getEntryById(db, id) ?? undefined,
+        typeFilter,
+    });
     // ── Scoring Phase ──────────────────────────────────────────────────────
     // Apply boosts as multiplicative factors (all boosts in a single phase
     // so that sort order and displayed scores are always consistent).
@@ -223,8 +176,6 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
     // user's intent. An exact name match is the strongest signal. Actionable
     // asset types (skills, commands, agents) are more useful than passive
     // reference docs. Curated metadata is more reliable than auto-generated.
-    const queryTokens = query.toLowerCase().split(/\s+/).filter(Boolean);
-    const queryLower = query.toLowerCase().trim();
     // Graph boost context (#207). Built once per query and reused across
     // every scored entry so the disk read + JSON parse only happens once
     // per search invocation. `null` when no graph file is present, when
@@ -237,170 +188,11 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
         // Search across all source dirs; the graph file lives next to the
         // primary source root. Cache misses are silent — the helper handles
         // missing files internally and returns `null` instead of throwing.
-        const primaryDir = allSourceDirs[0];
-        if (!primaryDir)
+        if (allSourceDirs.length === 0)
             return null;
-        return loadGraphBoostContext(primaryDir, query);
+        return loadGraphBoostContext(allSourceDirs, query, config, db);
     })();
-    for (const item of scored) {
-        const entry = item.entry;
-        let boostSum = 0;
-        // ── 1. Exact / near-exact name match (strongest signal) ──
-        // If the query IS the asset name (or very close), this is almost certainly
-        // what the user wants. This is the single most important ranking signal.
-        const nameLower = entry.name.toLowerCase();
-        const rawNameBase = nameLower.split("/").pop() ?? nameLower; // last segment for path-based names
-        const nameBase = entry.type === "memory" && rawNameBase.endsWith(".derived")
-            ? rawNameBase.slice(0, -".derived".length)
-            : rawNameBase;
-        if (nameBase === queryLower || nameLower === queryLower) {
-            // Exact match: massive boost
-            boostSum += 2.0;
-        }
-        else if (nameBase.includes(queryLower) || queryLower.includes(nameBase)) {
-            // Near-exact: query is substring of name or vice versa
-            boostSum += 1.0;
-        }
-        else {
-            // Token overlap: how many query tokens appear in the base name?
-            const nameTokens = nameBase.split(/[-_\s]+/).filter(Boolean);
-            const matchCount = queryTokens.filter((qt) => nameTokens.some((nt) => nt === qt || nt.includes(qt))).length;
-            if (matchCount > 0) {
-                // Proportional to how many query tokens match (0.3 per token, max 0.9)
-                boostSum += Math.min(0.9, matchCount * 0.3);
-            }
-        }
-        // ── 2. Type relevance boost ──
-        // Actionable assets (skills, commands, agents) are generally more useful
-        // than passive reference material when the user is searching for something
-        // to use. Knowledge docs are reference — valuable but secondary.
-        const TYPE_BOOST = {
-            skill: 0.4,
-            command: 0.35,
-            workflow: 0.35,
-            agent: 0.3,
-            script: 0.2,
-            memory: 0.1,
-            knowledge: 0,
-        };
-        boostSum += TYPE_BOOST[entry.type] ?? 0;
-        // ── 2.5. Derived-vs-raw memory preference ──
-        // Raw memories are user notes and may be incomplete or unvetted. Compressed
-        // `.derived` memories are the higher-signal retrieval target, but the
-        // preference should stay modest so stronger relevance signals still dominate.
-        if (entry.type === "memory") {
-            if (entry.name.toLowerCase().endsWith(".derived")) {
-                boostSum += 0.18;
-            }
-            else {
-                boostSum -= 0.08;
-            }
-        }
-        // ── 3. Tag exact match ──
-        // Exact tag equality is a strong signal — the author explicitly tagged
-        // this asset with the user's search term.
-        if (entry.tags) {
-            let tagBoost = 0;
-            for (const tag of entry.tags) {
-                if (queryTokens.some((t) => tag.toLowerCase() === t)) {
-                    tagBoost += 0.15;
-                }
-            }
-            boostSum += Math.min(0.3, tagBoost);
-        }
-        // ── 4. Search hint match ──
-        // Hints are author-curated retrieval cues (e.g. "use when deploying to k8s").
-        if (entry.searchHints) {
-            let hintBoost = 0;
-            for (const hint of entry.searchHints) {
-                const hintLower = hint.toLowerCase();
-                for (const token of queryTokens) {
-                    if (hintLower.includes(token)) {
-                        hintBoost += 0.12;
-                        break;
-                    }
-                }
-            }
-            boostSum += Math.min(0.24, hintBoost);
-        }
-        // ── 5. Alias match ──
-        // Aliases are alternate names the author defined for discovery.
-        if (entry.aliases) {
-            for (const alias of entry.aliases) {
-                const aliasLower = alias.toLowerCase();
-                if (aliasLower === queryLower) {
-                    boostSum += 1.5; // Nearly as strong as exact name match
-                    break;
-                }
-                if (queryTokens.some((t) => aliasLower.includes(t))) {
-                    boostSum += 0.3;
-                }
-            }
-        }
-        // ── 6. Description relevance ──
-        // All query tokens appearing in description suggests strong relevance.
-        if (entry.description) {
-            const descLower = entry.description.toLowerCase();
-            const descMatchCount = queryTokens.filter((t) => descLower.includes(t)).length;
-            if (descMatchCount === queryTokens.length && queryTokens.length > 1) {
-                // All query tokens found in description — high relevance
-                boostSum += 0.25;
-            }
-            else if (descMatchCount > 0) {
-                boostSum += 0.1;
-            }
-        }
-        // ── 7. Metadata quality signals ──
-        // Curated metadata is the only boost-bearing quality marker. `generated`
-        // and `proposed` (and unknown values) get no boost. `proposed` is also
-        // filtered out by default downstream (v1 spec §4.2).
-        const qualityBoost = entry.quality === "curated" ? 0.05 : 0;
-        boostSum += qualityBoost;
-        const confidenceBoost = typeof entry.confidence === "number" ? Math.min(0.05, Math.max(0, entry.confidence) * 0.05) : 0;
-        boostSum += confidenceBoost;
-        // ── 8. Graph signal (opt-in, #207) ──
-        // When the graph-extraction pass has produced a `graph.json`,
-        // contribute an additive boost based on how many of this entry's
-        // extracted entities match the query (or are one hop away from a
-        // match). Computed inside the same loop so all boosts are in one
-        // place and the per-call cost is one map lookup when the graph is
-        // absent. There is no parallel scoring track — `boostSum` is the
-        // single accumulator and the existing `MAX_BOOST_SUM` cap below
-        // applies to graph contributions exactly as it does to every other
-        // boost.
-        if (graphContext) {
-            boostSum += computeGraphBoost(graphContext, item.filePath);
-        }
-        const cappedBoost = Math.min(boostSum, MAX_BOOST_SUM);
-        item.score = item.score * (1 + cappedBoost);
-    }
-    // Utility-based re-ranking (MemRL pattern).
-    // After the FTS+boost scoring pass, apply a multiplicative
-    // utility factor based on aggregated usage telemetry.
-    // Batch-load all utility scores in one query to avoid N+1.
-    const UTILITY_WEIGHT = 0.5;
-    const UTILITY_MAX_BOOST = 1.5; // Cap at 1.5x multiplier
-    const RECENCY_DECAY_DAYS = 30;
-    const utilScoresMap = getUtilityScoresByIds(db, scored.map((s) => s.id));
-    for (const item of scored) {
-        const utilScore = utilScoresMap.get(item.id);
-        if (utilScore && utilScore.utility > 0) {
-            // Compute recency factor: exponential decay based on days since last use
-            let recencyFactor = 1;
-            if (utilScore.lastUsedAt) {
-                const lastUsedMs = new Date(utilScore.lastUsedAt).getTime();
-                const daysSinceLastUse = Number.isNaN(lastUsedMs)
-                    ? Infinity
-                    : Math.max(0, (Date.now() - lastUsedMs) / (1000 * 60 * 60 * 24));
-                recencyFactor = Math.exp(-daysSinceLastUse / RECENCY_DECAY_DAYS);
-            }
-            // Compute raw utility boost and cap it
-            const rawBoost = 1 + utilScore.utility * recencyFactor * UTILITY_WEIGHT;
-            const cappedBoost = Math.min(rawBoost, UTILITY_MAX_BOOST);
-            item.score = item.score * cappedBoost;
-            item.utilityBoosted = true;
-        }
-    }
+    applyRankingRules({ db, query, items: scored, graphContext });
     // ── minScore floor ──────────────────────────────────────────────────────
     // Drop semantic-only hits (cosine-only, no FTS match) whose score falls
     // below the configured floor. FTS hits and hybrid hits are always kept.
@@ -424,8 +216,9 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
     const qualityFiltered = includeProposed
         ? scopeFiltered
         : scopeFiltered.filter((item) => !isProposedQuality(item.entry.quality));
+    const beliefFiltered = qualityFiltered.filter((item) => matchBeliefFilter(item.entry.type, item.entry.beliefState, beliefFilter));
     const rankMs = Date.now() - tRank0;
-    const selected = qualityFiltered.slice(0, limit);
+    const selected = beliefFiltered.slice(0, limit);
     const hits = await Promise.all(selected.map(({ entry, filePath, score, rankingMode, utilityBoosted }) => {
         // CLAUDE.md locks SearchHit.score in [0,1]. The boost loop above can
         // exceed 1.0 (this was a pre-existing breach that #207's graph boost
@@ -444,11 +237,21 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
             sources,
             config,
             utilityBoosted,
+            graphContext,
             rendererRegistry,
         });
     }));
     return { embedMs, rankMs, hits };
 }
+function matchBeliefFilter(type, beliefState, filter) {
+    if (filter === "all")
+        return true;
+    if (type !== "memory")
+        return true;
+    if (filter === "current")
+        return beliefState === undefined || beliefState === "active";
+    return beliefState === "contradicted" || beliefState === "superseded" || beliefState === "archived";
+}
 // ── Vector scorer ───────────────────────────────────────────────────────────
 async function tryVecScores(db, query, k, config) {
     const semanticStatus = getEffectiveSemanticStatus(config, readSemanticStatus());
@@ -490,6 +293,7 @@ export async function buildDbHit(input) {
     // Round to 4 decimal places, no boost multiplication
     const score = Math.round(input.score * 10000) / 10000;
     const whyMatched = buildWhyMatched(input.entry, input.query, input.rankingMode, qualityBoost, confidenceBoost, input.utilityBoosted);
+    const graphHit = input.graphContext ? collectGraphRelatedHit(input.graphContext, input.path) : null;
     const source = findSourceForPath(input.path, input.sources);
     const ref = resolveSearchHitRef(input.entry, input.entry.name, source);
     const editable = isEditable(input.path, input.config);
@@ -514,11 +318,15 @@ export async function buildDbHit(input) {
         // Surface optional quality (v1 spec §4.2). Omitted when entry has
         // no `quality` field so payloads stay compact for the common case.
         ...(input.entry.quality ? { quality: input.entry.quality } : {}),
+        ...(input.entry.beliefState ? { beliefState: input.entry.beliefState } : {}),
+        ...(input.entry.currentBeliefRefs ? { currentBeliefRefs: input.entry.currentBeliefRefs } : {}),
+        ...(graphHit ? { graph: { entities: graphHit.entities, relations: graphHit.relations } } : {}),
     };
-    const renderer = await rendererForType(input.entry.type, rendererRegistry);
-    if (renderer?.enrichSearchHit) {
-        renderer.enrichSearchHit(hit, entryStashDir);
-    }
+    await enrichSearchHit(hit, {
+        type: input.entry.type,
+        stashDir: entryStashDir,
+        rendererRegistry,
+    });
     return hit;
 }
 export function buildWhyMatched(entry, query, 
@@ -565,6 +373,12 @@ rankingMode, qualityBoost, confidenceBoost, utilityBoosted) {
         reasons.push("curated metadata boost");
     if (confidenceBoost > 0)
         reasons.push("metadata confidence boost");
+    if (entry.beliefState === "active")
+        reasons.push("active belief state");
+    if (entry.beliefState === "contradicted")
+        reasons.push("contradicted belief state");
+    if (entry.beliefState === "superseded")
+        reasons.push("superseded belief state");
     if (utilityBoosted)
         reasons.push("usage history boost");
     return reasons;
@@ -585,7 +399,7 @@ export function deriveSize(bytes) {
  * precondition is always met regardless of caller.
  */
 function deduplicateByPath(items) {
-    const sorted = [...items].sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
+    const sorted = [...items].sort((a, b) => (b.score ?? 0) - (a.score ?? 0) || a.filePath.localeCompare(b.filePath));
     const seen = new Set();
     return sorted.filter((item) => {
         if (seen.has(item.filePath))