akm-cli 0.9.16 → 0.9.17-alpha.10

package/dist/indexer/search/db-search.js

@@ -2,41 +2,34 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
- * Database-backed (SQLite + FTS5/vector) source search implementation.
+ * Database-backed (SQLite FTS5 + vector) search.
  *
- * Extracted from source-search.ts to break the circular import:
- *   source-search.ts → sources/providers/filesystem.ts → db-search.ts (no cycle)
- *
- * source-search.ts imports this module for the `searchLocal` export.
- * sources/providers/filesystem.ts also imports `searchLocal` from here.
- *
- * Renamed from `local-search.ts` to signal that this is the DB-layer search
- * implementation, not a "local vs. remote" distinction.
+ * Ranking is two candidate channels fused by reciprocal rank (`ranking.ts`):
+ * BM25 over whole documents matching any query word, and the nearest document
+ * vectors to the query embedding. Filters narrow the fused list; nothing else
+ * reorders it.
  */
 import path from "node:path";
-import { buildActionFromContributors, defaultActionContributors } from "../../core/action-contributors.js";
 import { stashDirFor } from "../../core/asset/asset-placement.js";
 import { displayRef } from "../../core/asset/resolve-ref.js";
 import { compareCodePoints } from "../../core/common.js";
 import { classifyPathAccess } from "../../core/path-access.js";
 import { getDbPath } from "../../core/paths.js";
 import { systemErrorCode } from "../../core/system-error.js";
-import { allowsFragmentRef, defaultRendererRegistry } from "../../core/type-presentation.js";
+import { presentationFor } from "../../core/type-presentation.js";
+import { embed } from "../../llm/embedder.js";
+import { applyEmbeddingTemplate, resolveEmbeddingProfile } from "../../llm/embedders/profile.js";
 import { normalizeEmbeddingEndpoint } from "../../llm/embedders/remote.js";
 import { assertIndexPathReadable, closeDatabase, openExistingDatabase, } from "../../storage/repositories/index-connection.js";
-import { getAllEntries, getBaseBeliefStatesForDerivedTwins, getEntryById, getEntryCount, getPositiveFeedbackCountsByIds, } from "../../storage/repositories/index-entries-repository.js";
-import { getIndexedMarkdownFragment, getIndexedMarkdownFragments, searchFts, } from "../../storage/repositories/index-fts-repository.js";
+import { getAllEntries, getBaseBeliefStatesForDerivedTwins, getEntryById, getEntryCount, getEntryRefsAndTypes, } from "../../storage/repositories/index-entries-repository.js";
+import { searchFts } from "../../storage/repositories/index-fts-repository.js";
 import { getMeta } from "../../storage/repositories/index-meta-repository.js";
 import { getEmbeddingCount, searchVec } from "../../storage/repositories/index-vec-repository.js";
-import { getCurrentWorkflowScopeKey } from "../../workflows/authoring/scope-key.js";
 import { ensureIndex } from "../ensure-index.js";
-import { collectGraphRelatedHit, loadGraphBoostContext } from "../graph/graph-boost.js";
 import { isProposedQuality } from "../passes/metadata.js";
-import { resolveProjectContext } from "../walk/project-context.js";
-import { buildLexicalQueryPlan, parseRefPrefixQuery, parseRetiredTypePrefixQuery, } from "./fts-query.js";
-import { applyRankingRules, combineSearchScores, lexicalNameMatchTier, normalizeFtsScores } from "./ranking.js";
-import { typeBoostFor } from "./ranking-contributors.js";
-import { attachSearchHitAttribution, copySearchHitAttribution, getSearchHitAttribution } from "./search-attribution.js";
+import { ftsQueryTokens, parseRefPrefixQuery, parseRetiredTypePrefixQuery } from "./fts-query.js";
+import { reciprocalRankFusion } from "./ranking.js";
+import { attachSearchHitAttribution } from "./search-attribution.js";
 import { enrichSearchHit } from "./search-hit-enrichers.js";
 import { buildEditHint, findSourceForPath, isEditable } from "./search-source.js";
 /**
@@ -47,6 +40,16 @@ import { buildEditHint, findSourceForPath, isEditable } from "./search-source.js
  * actionable without re-introducing read-triggered reindexing.
  */
 const STALE_INDEX_HINT_MS = 7 * 24 * 60 * 60 * 1000;
+/** Candidates each channel contributes to fusion. */
+const CHANNEL_DEPTH = 100;
+/** How long search waits for the query embedding unless `embedding.queryTimeoutMs` says otherwise. */
+export const DEFAULT_QUERY_EMBED_TIMEOUT_MS = 3000;
+/** Each search hit's indexed content, kept off the output object for curate's reranker. */
+const hitContent = new WeakMap();
+/** The indexed (safe-projected) content of a hit this process's search returned. */
+export function searchHitContent(hit) {
+    return hitContent.get(hit);
+}
 function hasIndexedProvenance(entry) {
     return Boolean(entry.itemRef && entry.bundleId && entry.conceptId);
 }
@@ -65,11 +68,8 @@ function buildStaleIndexHint(db) {
         return undefined;
     }
 }
-function indexedProvenance(entry) {
-    return { itemRef: entry.itemRef, bundleId: entry.bundleId, conceptId: entry.conceptId };
-}
-export function buildLocalAction(type, ref, registry = defaultRendererRegistry) {
-    return buildActionFromContributors({ type, ref }, defaultActionContributors(registry)) ?? `akm show ${ref}`;
+export function buildLocalAction(type, ref) {
+    return presentationFor(type).action?.(ref) ?? `akm show ${ref}`;
 }
 function resolveSearchHitRef(entry, provenance, defaultBundleId) {
     return displayRef({
@@ -79,26 +79,6 @@ function resolveSearchHitRef(entry, provenance, defaultBundleId) {
         bundleId: provenance.bundleId,
     }, defaultBundleId);
 }
-function resolveSearchHitOrigin(source) {
-    return source?.registryId ?? null;
-}
-/**
- * Phase 2A / Rec 5: gate for the per-search `getPositiveFeedbackCountsByIds`
- * lookup. Returns `true` only when the user has explicitly opted into
- * `improve.utilityDecay` AND configured a `feedbackStabilityBoost > 1.0`.
- * Either condition being false makes the DB query pure overhead (the ranking
- * contributor ignores `positiveFeedbackCounts` when `utilityDecayConfig` is
- * absent, and `1.0^count == 1` collapses the boost into a no-op).
- *
- * Exported for unit testing — keeps the gate decision pinned so a future edit
- * can't quietly broaden the hot path.
- */
-export function shouldQueryPositiveFeedbackCounts(utilityDecayRaw) {
-    if (utilityDecayRaw === undefined)
-        return false;
-    const boost = utilityDecayRaw.feedbackStabilityBoost ?? 1.5;
-    return boost > 1.0;
-}
 // ── Main search entrypoint ───────────────────────────────────────────────────
 /**
  * Whether an embedding provider is actually configured.
@@ -116,18 +96,9 @@ function hasConfiguredEmbeddingProvider(config) {
     return Boolean(config.embedding?.endpoint && config.embedding?.model);
 }
 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 restrictToSources = input.restrictToSources === true;
-    const includeExcludedTypes = input.includeExcludedTypes === true;
-    const disableProjectContext = input.disableProjectContext === true;
-    const disableScopedUtility = input.disableScopedUtility === true;
-    const rendererRegistry = input.rendererRegistry ?? defaultRendererRegistry;
-    const allSourceDirs = sources.map((s) => s.path);
+    const { query, stashDir, config } = input;
     const warnings = [];
-    // Semantic search is attempted fresh on every query (see `tryVecScores`);
+    // Semantic search is attempted fresh on every query (see `startVectorChannel`);
     // there is no cached readiness verdict to consult here. The only thing
     // worth flagging ahead of the attempt is a config that can never succeed.
     if (config.semanticSearchMode === "auto" && !hasConfiguredEmbeddingProvider(config)) {
@@ -167,7 +138,7 @@ export async function searchLocal(input) {
         const staleHint = buildStaleIndexHint(db);
         if (staleHint)
             warnings.push(staleHint);
-        const { hits, embedMs, rankMs, mode, semanticWarning } = await searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry, filters, includeProposed, beliefFilter, restrictToSources, includeExcludedTypes, disableProjectContext, disableScopedUtility);
+        const { hits, embedMs, rankMs, mode, semanticWarning } = await searchDatabase(db, input);
         if (semanticWarning)
             warnings.push(semanticWarning);
         return {
@@ -177,7 +148,7 @@ export async function searchLocal(input) {
             embedMs,
             rankMs,
             // Report the mode the search ACTUALLY used, carried explicitly from the
-            // vector scorer — not inferred from elapsed embedding milliseconds.
+            // vector channel — not inferred from elapsed embedding milliseconds.
             mode,
         };
     }
@@ -186,326 +157,142 @@ export async function searchLocal(input) {
     }
 }
 // ── Database search ─────────────────────────────────────────────────────────
-/**
- * Keep public scores in [0, 1] without flattening every boosted result to the
- * same hard-clamped value. The ranking pipeline deliberately keeps its raw
- * score for deterministic ordering before stable path deduplication; this
- * monotone display projection preserves that order and leaves visible
- * separation for graph, type, and project-context signals.
- */
-function displaySearchScore(score) {
-    return 1 - Math.exp(-Math.max(0, score));
-}
-/**
- * A final deterministic key for genuinely tied candidates.  It deliberately
- * excludes the asset name, filename, path, durable ref, and SQLite id: callers
- * such as the memory-pack adapter generate each of those from an opaque source
- * id, so using one here makes an otherwise equal search depend on that id.
- *
- * The normal AKM Markdown adapter keeps an H1 title in `content`; strip that
- * one synthetic title too, because the adapter may derive it from the opaque
- * filename.  Identical remaining bodies are semantically indistinguishable at
- * this ranking stage and intentionally continue to the existing name/path
- * fallback for repeatable local presentation.
- */
-function asciiCaseFold(value) {
-    // SQLite's built-in lower() folds ASCII only unless a build opts into ICU.
-    // Keep this key deliberately in that portable shared subset instead of
-    // introducing locale-dependent JavaScript ordering for non-ASCII content.
-    return value.replace(/[A-Z]/g, (letter) => String.fromCharCode(letter.charCodeAt(0) + 32));
-}
-/** The portable byte-level title/body rule mirrored in index-fts-repository. */
-export function canonicalContentTieKey(entry) {
-    const content = entry.content ?? "";
-    const newline = content.startsWith("# ") ? content.indexOf("\n") : -1;
-    // SQLite uses ltrim(value, char(13) || char(10) || ' ') after an exact '# '
-    // title and trim(value, ' ') otherwise. Keep exactly that deliberately
-    // narrow byte contract; do not use locale or Unicode-whitespace helpers.
-    const body = newline >= 0 ? content.slice(newline + 1).replace(/^[\r\n ]+/, "") : content;
-    const source = (body || entry.description || "").replace(/^ +| +$/g, "");
-    return Buffer.from(asciiCaseFold(source), "utf8").toString("hex");
-}
-function buildSearchResultComparator(query) {
-    const queryTokens = buildLexicalQueryPlan(query).tokens.map((token) => token.toLowerCase());
-    const displayScore = (score) => Math.round(displaySearchScore(score) * 10000) / 10000;
-    const stableRankScore = (score) => Math.round(score * 10000) / 10000;
-    return (a, b) => {
-        const aNameTier = lexicalNameMatchTier(a.entry, queryTokens);
-        const bNameTier = lexicalNameMatchTier(b.entry, queryTokens);
-        if (aNameTier === 3 || bNameTier === 3) {
-            const nameDiff = bNameTier - aNameTier;
-            if (nameDiff !== 0)
-                return nameDiff;
-        }
-        const scoreDiff = displayScore(b.score) - displayScore(a.score);
-        if (scoreDiff !== 0)
-            return scoreDiff;
-        const rawScoreDiff = stableRankScore(b.score) - stableRankScore(a.score);
-        if (rawScoreDiff !== 0)
-            return rawScoreDiff;
-        // Ceiling values are intentionally allowed to demote visibility, but not
-        // to erase relevance. Prefer the score before a relaxed body-only ceiling;
-        // a later belief-state ceiling has its own minScore handoff and must not
-        // overwrite this ordering evidence. Belief-only ceilings fall back to
-        // their `preCeilingScore`.
-        const preCeilingRelevance = (item) => item.preRelaxedCeilingScore ?? item.preCeilingScore ?? item.score;
-        const ceilingDiff = stableRankScore(preCeilingRelevance(b)) - stableRankScore(preCeilingRelevance(a));
-        if (ceilingDiff !== 0)
-            return ceilingDiff;
-        const nameDiff = bNameTier - aNameTier;
-        if (nameDiff !== 0)
-            return nameDiff;
-        const typeDiff = typeBoostFor(b.entry.type) - typeBoostFor(a.entry.type);
-        if (typeDiff !== 0)
-            return typeDiff;
-        // Keep opaque generated IDs out of the final relevance tie-break.  This
-        // runs only after every ranking contributor (including the #940 preserved
-        // pre-ceiling evidence), exact-name, and type comparison has tied.
-        const contentDiff = compareCodePoints(canonicalContentTieKey(a.entry), canonicalContentTieKey(b.entry));
-        if (contentDiff !== 0)
-            return contentDiff;
-        return a.filePath.localeCompare(b.filePath);
+async function searchDatabase(db, input) {
+    const { query, searchType, limit, stashDir, sources, config, filters } = input;
+    const filterOptions = {
+        db,
+        sources,
+        restrictToSources: input.restrictToSources === true,
+        filters,
+        includeProposed: input.includeProposed === true,
+        beliefFilter: input.beliefFilter ?? "all",
     };
-}
-async function searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry = defaultRendererRegistry, filters, includeProposed = false, beliefFilter = "all", restrictToSources = false, includeExcludedTypes = false, disableProjectContext = false, disableScopedUtility = false) {
-    const hasSearchableTokens = query.length > 0 && buildLexicalQueryPlan(query).tokens.length > 0;
     // #627 — resolve the default type-exclusion policy. It applies ONLY on the
     // untyped ('any') path and only when the caller did not opt back in via
     // `includeExcludedTypes`. When the config key is ABSENT a built-in default of
     // ['session'] is applied; an explicit empty list disables exclusion.
-    const defaultExcludes = searchType === "any" && !includeExcludedTypes ? (config.search?.defaultExcludeTypes ?? ["session"]) : [];
+    const defaultExcludes = searchType === "any" && !input.includeExcludedTypes ? (config.search?.defaultExcludeTypes ?? ["session"]) : [];
     // D4 — conceptId-prefix queries (`memories/projecta/`, `bundle//`,
     // `bundle//skills/`) translate to a deterministic enumeration narrowed by
-    // conceptId, instead of degenerating into the AND-token FTS query their
-    // sanitized form would produce ("memories projecta" — noise). The branch
+    // conceptId instead of a keyword search over their path words. The branch
     // fires only on the untyped path: an explicit `--type` flag expresses
     // stronger intent and wins. The PREFIX is itself explicit intent, so
     // `defaultExcludeTypes` does not apply — `sessions/` enumerates sessions
     // exactly like `--type session` does, and `bundle//` means the whole bundle.
     const refPrefix = searchType === "any" ? parseRefPrefixQuery(query) : null;
-    // Shared args for the two browse paths below; browse never runs semantic
-    // ranking, so both return usedSemantic: false.
-    const browseArgs = {
-        db,
-        query,
-        limit,
-        stashDir,
-        allSourceDirs,
-        sources,
-        config,
-        rendererRegistry,
-        filters,
-        includeProposed,
-        beliefFilter,
-        restrictToSources,
-    };
     if (refPrefix) {
-        // Browse path (conceptId-prefix enumeration).
         return {
-            ...(await enumerateEntries({
-                ...browseArgs,
+            hits: await enumerateEntries({
+                ...filterOptions,
+                limit,
+                stashDir,
+                config,
                 excludeTypes: [],
                 conceptIdPrefix: refPrefix.conceptIdPrefix,
                 ...(refPrefix.bundle !== undefined ? { bundle: refPrefix.bundle } : {}),
-            })),
+            }),
             mode: "keyword",
         };
     }
-    // Empty queries — including ones that sanitize down to no searchable FTS
-    // tokens such as "." — should enumerate matching entries instead of
-    // returning an empty result set from FTS.
-    if (!hasSearchableTokens) {
-        // Browse path (empty/unsearchable query).
+    // Empty queries — including ones with no searchable token such as "." —
+    // enumerate matching entries instead of returning nothing.
+    if (ftsQueryTokens(query).length === 0) {
         return {
-            ...(await enumerateEntries({
-                ...browseArgs,
+            hits: await enumerateEntries({
+                ...filterOptions,
+                limit,
+                stashDir,
+                config,
                 typeFilter: searchType === "any" ? undefined : searchType,
                 excludeTypes: defaultExcludes,
-            })),
+            }),
             mode: "keyword",
         };
     }
-    // Start the async embedding request without awaiting, then run FTS
-    // synchronously while the HTTP/local embedding request is in-flight.
     const typeFilter = searchType === "any" ? undefined : searchType;
-    const { ftsResults, embeddingScores, embedMs, mode, semanticWarning } = await collectSearchSignals(db, query, limit * 3, typeFilter, defaultExcludes, config);
+    const startedAt = Date.now();
+    // The query embedding request goes out first, so FTS runs while it is in flight.
+    const vectorChannel = startVectorChannel(db, query, config);
+    const lexical = searchFts(db, query, CHANNEL_DEPTH, typeFilter, defaultExcludes);
+    const vector = await vectorChannel;
+    const embedMs = Date.now() - startedAt;
     const tRank0 = Date.now();
-    // ── Score normalization ──────────────────────────────────────────────
-    // Stable bounded BM25 transform + cosine similarity with weighted addition
-    // (FTS 0.7, vector 0.3). The lexical transform is per-row, so widening the
-    // candidate set cannot alter a pre-existing row's base score.
-    const ftsScoreMap = normalizeFtsScores(ftsResults);
-    // Build embedding score map (cosine similarities already 0-1)
-    const embedScoreMap = new Map();
-    if (embeddingScores) {
-        for (const [id, cosine] of embeddingScores) {
-            embedScoreMap.set(id, cosine);
+    const vectorCandidates = vector.neighbors ? keepAllowedTypes(db, vector.neighbors, typeFilter, defaultExcludes) : [];
+    const fused = reciprocalRankFusion([lexical, vectorCandidates]);
+    const selected = selectFusedEntries(db, fused, limit, filterOptions);
+    const rankMs = Date.now() - tRank0;
+    const hits = await Promise.all(selected.map(({ candidate, row }) => buildDbHit({
+        entry: row.entry,
+        path: row.filePath,
+        itemRef: row.itemRef,
+        bundleId: row.bundleId,
+        conceptId: row.conceptId,
+        score: Math.round(candidate.score * 1e6) / 1e6,
+        whyMatched: describeRanks(candidate),
+        defaultStashDir: stashDir,
+        sources,
+        config,
+        db,
+    })));
+    const mode = vector.warning ? "fts-fallback" : vector.neighbors ? "semantic" : "keyword";
+    return { embedMs, rankMs, hits, mode, semanticWarning: vector.warning };
+}
+/**
+ * Walk the fused list in order, loading entries a batch at a time, and keep
+ * the first `limit` that survive path deduplication and the filters. An entry
+ * whose indexed content is identical to a kept one's (the same body saved
+ * under another name or in another bundle) is a duplicate and is skipped.
+ */
+function selectFusedEntries(db, fused, limit, filterOptions) {
+    const selected = [];
+    const seenPaths = new Set();
+    const seenContent = new Set();
+    const batchSize = Math.max(limit * 2, 20);
+    for (let offset = 0; offset < fused.length && selected.length < limit; offset += batchSize) {
+        const batch = [];
+        for (const candidate of fused.slice(offset, offset + batchSize)) {
+            const row = getEntryById(db, candidate.id);
+            if (!row || !hasIndexedProvenance(row) || seenPaths.has(row.filePath))
+                continue;
+            seenPaths.add(row.filePath);
+            batch.push({ ...row, id: candidate.id, candidate });
+        }
+        for (const kept of applyEntryFilters(batch, filterOptions)) {
+            const { candidate, ...row } = kept;
+            const content = row.entry.content?.replace(/\s+/g, " ").trim();
+            if (content) {
+                if (seenContent.has(content))
+                    continue;
+                seenContent.add(content);
+            }
+            selected.push({ candidate, row });
         }
     }
-    // ── Combine FTS + vector scores ──────────────────────────────────────
-    const scored = combineSearchScores({
-        ftsScoreMap,
-        embedScoreMap,
-        getEntryById: (id) => getEntryById(db, id) ?? undefined,
-        typeFilter,
-        // #627 — also exclude default-hidden types from the vector-only branch so a
-        // session asset that is a top-k vector neighbor (but not an FTS match) does
-        // not leak into default ('any') results. defaultExcludes is already []
-        // unless this is the untyped path without includeExcludedTypes.
-        excludeTypes: defaultExcludes,
-    }).filter(hasIndexedProvenance);
-    // ── Scoring Phase ──────────────────────────────────────────────────────
-    // Apply boosts as multiplicative factors (all boosts in a single phase
-    // so that sort order and displayed scores are always consistent).
-    // Ranking philosophy: the goal is to surface the MOST USEFUL result for the
-    // 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.
-    // 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
-    // the schema doesn't match, or when no query token matches a graph
-    // entity — in all of those cases the per-entry call is skipped and
-    // graph contributes nothing. The graph signal feeds this single
-    // FTS5+boosts loop as ONE additive component (CLAUDE.md / spec §6:
-    // one scoring pipeline, no parallel SearchHit scorer).
-    const graphContext = (() => {
-        // 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.
-        if (allSourceDirs.length === 0)
-            return null;
-        return loadGraphBoostContext(allSourceDirs, query, config, db);
-    })();
-    // Resolve project-context tokens from the current working directory once
-    // per search invocation. Returns null when running from home dir / /tmp,
-    // or when the caller passed `--no-project-context` (disableProjectContext).
-    const projectContext = disableProjectContext ? null : resolveProjectContext(process.cwd());
-    // Phase 2A / Rec 5: resolve forgetting-curve config and skip the feedback
-    // count query when the boost cannot make a difference (default ≤ 1.0 means
-    // boost^count == 1 — zero overhead for the common case).
-    const utilityDecayRaw = config.improve?.utilityDecay;
-    const halfLifeDays = utilityDecayRaw?.halfLifeDays ?? 30;
-    const feedbackStabilityBoost = utilityDecayRaw?.feedbackStabilityBoost ?? 1.5;
-    const utilityDecayConfig = utilityDecayRaw !== undefined ? { halfLifeDays, feedbackStabilityBoost } : undefined;
-    // Gate the feedback-count query on the user having explicitly opted into
-    // utilityDecay. Without an opt-in, `utilityDecayConfig` is undefined and the
-    // ranking contributor ignores `positiveFeedbackCounts` — so running the DB
-    // query here would be pure overhead. The boost > 1.0 sub-gate then skips the
-    // query when the configured boost is a no-op (1.5^count when boost==1 is 1).
-    const positiveFeedbackCounts = shouldQueryPositiveFeedbackCounts(utilityDecayRaw)
-        ? getPositiveFeedbackCountsByIds(scored.map((item) => item.id))
-        : undefined;
-    // Resolve per-project scope key for scoped utility scoring.
-    // `disableScopedUtility` (wired from `akm search --no-project-context`)
-    // opts out (e.g. for registry searches or tests).
-    let scopeKey;
-    try {
-        scopeKey = disableScopedUtility ? undefined : getCurrentWorkflowScopeKey();
-    }
-    catch {
-        // Non-fatal — ranking proceeds without scoped utility on any error.
-    }
-    // 03-R3: derived twins inherit their base's demoting belief state before
-    // ranking, so the (03) belief-state ranker demotes a stale flag-free twin.
-    inheritDerivedTwinBeliefStates(db, scored);
-    applyRankingRules({
-        db,
-        query,
-        items: scored,
-        graphContext,
-        projectContext,
-        utilityDecayConfig,
-        positiveFeedbackCounts,
-        scopeKey,
-    });
-    // ── 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.
-    // Default floor: 0.2. Set search.minScore = 0 in config to disable.
-    // Judged on the PRE-ceiling score when a demoting belief state clamped the
-    // item (`preCeilingScore`): the belief ceilings can sit below this floor
-    // (archived 0.15 < 0.2), and a demotion must rank the hit last, not
-    // silently remove a result that would otherwise have listed.
-    const minScore = config.search?.minScore ?? 0.2;
-    const preFilter = minScore > 0
-        ? scored.filter((item) => item.rankingMode !== "semantic" || (item.preCeilingScore ?? item.score) >= minScore)
-        : scored;
-    preFilter.sort(buildSearchResultComparator(query));
-    // Deduplicate by file path — keep only the highest-scored entry per file.
-    const deduped = deduplicateByPath(preFilter);
-    // Source → scope → proposed-quality → derived-twin belief inheritance →
-    // belief: the post-candidate filter chain shared with enumerateEntries (see
-    // applyEntryFilters). Applied AFTER ranking so filtering narrows the result
-    // set without touching the single FTS5+boosts scoring pipeline. The twin
-    // inheritance inside the chain re-runs here as an idempotent no-op — it
-    // already ran on the full candidate pool before ranking (:460) to feed the
-    // belief-state ranker.
-    const beliefFiltered = applyEntryFilters(deduped, {
-        db,
-        sources,
-        restrictToSources,
-        filters,
-        includeProposed,
-        beliefFilter,
-    });
-    const rankMs = Date.now() - tRank0;
-    const selected = beliefFiltered.slice(0, limit);
-    const fragmentSelections = selected.flatMap((ranked) => ranked.fragmentId && allowsFragmentRef(ranked.entry.type) && hasIndexedProvenance(ranked)
-        ? [{ entryId: ranked.id, itemRef: ranked.itemRef, fragmentId: ranked.fragmentId }]
-        : []);
-    const selectedFragments = getIndexedMarkdownFragments(db, fragmentSelections);
-    const selectedFragmentByEntryId = new Map();
-    fragmentSelections.forEach((selection, index) => {
-        selectedFragmentByEntryId.set(selection.entryId, selectedFragments[index]);
-    });
-    const hits = await Promise.all(selected.map((ranked) => {
-        const { entry, filePath, score, rankingMode, utilityBoosted } = ranked;
-        // CLAUDE.md locks SearchHit.score in [0,1]. The boost loop deliberately
-        // remains raw for ranking, then takes a monotone bounded projection at
-        // the public boundary so contributors do not collapse into hard-clamped
-        // ties.
-        const finalScore = displaySearchScore(score);
-        return buildDbHit({
-            entry,
-            path: filePath,
-            ...indexedProvenance(ranked),
-            score: Math.round(finalScore * 10000) / 10000,
-            query,
-            rankingMode,
-            lexicalMatch: ranked.lexicalMatch,
-            fragmentId: ranked.fragmentId,
-            indexedFragment: ranked.fragmentId ? (selectedFragmentByEntryId.get(ranked.id) ?? null) : undefined,
-            defaultStashDir: stashDir,
-            allSourceDirs,
-            sources,
-            config,
-            utilityBoosted,
-            graphContext,
-            attributionSource: ranked,
-            rendererRegistry,
-            db,
-        });
-    }));
-    return { embedMs, rankMs, hits, mode, semanticWarning };
+    return selected.slice(0, limit);
 }
-async function collectSearchSignals(db, query, candidateLimit, typeFilter, excludeTypes, config) {
-    const startedAt = Date.now();
-    const embeddingPromise = tryVecScores(db, query, candidateLimit, config);
-    const ftsResults = searchFts(db, query, candidateLimit, typeFilter, excludeTypes);
-    const embeddingResult = await embeddingPromise;
-    const mode = embeddingResult.warning
-        ? "fts-fallback"
-        : embeddingResult.scores !== null
-            ? "semantic"
-            : "keyword";
-    return {
-        ftsResults,
-        embeddingScores: embeddingResult.scores,
-        embedMs: Date.now() - startedAt,
-        mode,
-        semanticWarning: embeddingResult.warning,
-    };
+/** Vector candidates of the requested type, nearest first; equal distances are ordered by ref. */
+function keepAllowedTypes(db, neighbors, typeFilter, excludeTypes) {
+    const rows = getEntryRefsAndTypes(db, neighbors.map((neighbor) => neighbor.id));
+    const excluded = new Set(excludeTypes);
+    return neighbors
+        .flatMap(({ id, distance }) => {
+        const row = rows.get(id);
+        if (!row)
+            return [];
+        if (typeFilter ? row.type !== typeFilter : excluded.has(row.type))
+            return [];
+        return [{ id, itemRef: row.itemRef, distance }];
+    })
+        .sort((a, b) => a.distance - b.distance || compareCodePoints(a.itemRef, b.itemRef))
+        .map(({ id, itemRef }) => ({ id, itemRef }));
+}
+/** `whyMatched` for a fused hit: its rank in each channel that returned it. */
+function describeRanks(candidate) {
+    const [lexicalRank, vectorRank] = candidate.ranks;
+    return [
+        ...(lexicalRank !== undefined ? [`lexical rank ${lexicalRank}`] : []),
+        ...(vectorRank !== undefined ? [`vector rank ${vectorRank}`] : []),
+    ];
 }
 /**
  * The no-hits tip. A query in the retired `<type>:` / `<type>:<prefix>/` browse
@@ -526,13 +313,13 @@ function emptyResultTip(query) {
 /**
  * Enumerate index entries without FTS scoring — the browse path shared by
  * empty/unsearchable queries and D4 conceptId-prefix queries (`memories/`,
- * `bundle//`, `bundle//skills/`). Applies the same post-ranking filters as the scored
+ * `bundle//`, `bundle//skills/`). Applies the same filters as the scored
  * path (source narrowing, scope, proposed-quality, belief) before the limit
  * slice. Hits carry the fixed browse score 1 in type-then-name order — this is
  * a deterministic listing, not a relevance ranking.
  */
 async function enumerateEntries(opts) {
-    const { db, query, sources, config, rendererRegistry, filters, beliefFilter } = opts;
+    const { db, sources, config } = opts;
     const allEntries = getAllEntries(db, opts.typeFilter, opts.excludeTypes).filter(hasIndexedProvenance);
     // Explicit listing order: type, then name, then filePath. The underlying
     // SELECT carries no ORDER BY, so its row order tracks the query plan and the
@@ -552,78 +339,34 @@ async function enumerateEntries(opts) {
     const prefixFiltered = conceptIdPrefix.length > 0
         ? bundleFiltered.filter((ie) => ie.conceptId.toLowerCase().startsWith(conceptIdPrefix))
         : bundleFiltered;
-    // Deduplicate by file path — multiple entries can share the same file
-    const seenFilePaths = new Set();
-    const uniqueEntries = prefixFiltered.filter((ie) => {
-        if (seenFilePaths.has(ie.filePath))
-            return false;
-        seenFilePaths.add(ie.filePath);
-        return true;
-    });
-    // Source → scope → proposed-quality → derived-twin belief inheritance →
-    // belief: the post-candidate filter chain shared with searchDatabase's
-    // scored path (see applyEntryFilters). Filtering happens BEFORE the limit
-    // slice so a restrictive filter still returns up to `limit` results. On this
-    // path the twin inheritance is the ONLY place it runs (there is no ranking
-    // pass), keeping the belief filter and reported hit state consistent with
-    // the scored path.
-    const beliefFiltered = applyEntryFilters(uniqueEntries, {
-        db,
-        sources,
-        restrictToSources: opts.restrictToSources,
-        filters,
-        includeProposed: opts.includeProposed,
-        beliefFilter,
-    });
-    const selected = beliefFiltered.slice(0, opts.limit);
-    const hits = await Promise.all(selected.map((ie) => buildDbHit({
+    // Deduplicate by file path — multiple entries can share the same file.
+    // Filtering happens BEFORE the limit slice so a restrictive filter still
+    // returns up to `limit` results.
+    const selected = applyEntryFilters(deduplicateByPath(prefixFiltered), opts).slice(0, opts.limit);
+    return Promise.all(selected.map((ie) => buildDbHit({
         entry: ie.entry,
         path: ie.filePath,
         itemRef: ie.itemRef,
         bundleId: ie.bundleId,
         conceptId: ie.conceptId,
         score: 1,
-        query,
-        rankingMode: "fts",
         defaultStashDir: opts.stashDir,
-        allSourceDirs: opts.allSourceDirs,
         sources,
         config,
-        rendererRegistry,
         db,
     })));
-    return { hits };
 }
 /**
- * Post-candidate filter chain shared by BOTH search paths — the scored path
- * (`searchDatabase`) and the browse path (`enumerateEntries`). Applies, in this
- * exact order: source-narrowing → scope → proposed-quality → derived-twin
- * belief inheritance → belief filter. Extracting the chain removes the two
- * paths' formerly-duplicated filter sequences so the predicates, their order,
- * and the twin-inheritance placement can never drift apart (plan §4.3).
- *
- * What this does NOT unify — and deliberately leaves divergent — is CANDIDATE-
- * POOL construction, which is inherent search-vs-browse semantics: the scored
- * path's pool is `searchFts`/vector matches for the query's own tokens (FTS
- * includes structured fields and bounded adapter content), while the
- * enumerate path's pool is `getAllEntries` for the type, independent of query
- * text. A derived twin sharing no indexed token with the query is therefore an
- * enumerate-path candidate but never a scored-path candidate. (A golden
- * fixture used to pin that divergence; the golden suites were deleted in
- * 0.9.8, so this comment is now the record of it.)
- *
- * `inheritDerivedTwinBeliefStates` is idempotent, so running it here is safe on
- * the scored path, which must ALSO call it before ranking (the belief-state
- * ranker demotes inherited states): by the time this chain runs, those twins
- * already carry a state and the call here is a no-op for them. The enumerate
- * path never ranks, so this is the only place it inherits.
+ * Filter chain shared by the scored and browse paths, in this order:
+ * source-narrowing → scope → proposed-quality → derived-twin belief
+ * inheritance → belief filter.
  */
 function applyEntryFilters(items, opts) {
     const { filters } = opts;
     // Source filter: when the caller narrowed `sources` via `--from <name>`,
     // drop entries whose filePath does not live under any requested source. The
-    // FTS/enumerate index spans every configured source, so without this filter a
-    // narrowed --from request would still leak results from other sources.
+    // index spans every configured source, so without this filter a narrowed
+    // --from request would still leak results from other sources.
     const sourceFiltered = opts.restrictToSources
         ? items.filter((item) => findSourceForPath(item.filePath, opts.sources) !== undefined)
         : items;
@@ -645,14 +388,12 @@ function applyEntryFilters(items, opts) {
 }
 /**
  * 03-R3: let each `.derived` twin inherit its base memory's demoting belief
- * state for this ranking pass, so a stale flag-free twin is demoted like its
- * corrected base. The base carries the flag (a contradicted base takes a real
- * ranking penalty); its near-duplicate `.derived` twin carries none and would
- * otherwise outrank the corrected copy. Done in-memory at search time — NOT by
- * writing the twin's frontmatter — because the SCC belief resolver refreshes any
- * non-frozen state written to a derived memory back to `active` on the next
- * improve run, erasing it. Only twins with no state of their own inherit; an
- * explicit twin state always wins. Reuses the (03) belief-state ranker + filter.
+ * state, so `--belief` treats a stale flag-free twin like its corrected base.
+ * The base carries the flag; its near-duplicate `.derived` twin carries none.
+ * Done in-memory at search time — NOT by writing the twin's frontmatter —
+ * because the SCC belief resolver refreshes any non-frozen state written to a
+ * derived memory back to `active` on the next improve run, erasing it. Only
+ * twins with no state of their own inherit; an explicit twin state always wins.
  */
 function inheritDerivedTwinBeliefStates(db, items) {
     const DEMOTING = new Set(["contradicted", "superseded", "deprecated", "archived"]);
@@ -687,33 +428,36 @@ function matchBeliefFilter(beliefState, filter) {
         beliefState === "deprecated" ||
         beliefState === "archived");
 }
-// ── Vector scorer ───────────────────────────────────────────────────────────
-async function tryVecScores(db, query, k, config) {
+// ── Vector channel ──────────────────────────────────────────────────────────
+/**
+ * Embed the query and return its nearest document ids, best first. The
+ * embedding request is dispatched before this returns, so the caller's FTS
+ * query overlaps it. A slow or failing embedder degrades the search to keyword
+ * ranking with a warning after `embedding.queryTimeoutMs`.
+ */
+function startVectorChannel(db, query, config) {
     if (config.semanticSearchMode === "off")
-        return { scores: null };
-    // A real-time completeness fact, not a cached verdict: skip the network
-    // round trip only when the index has never embedded anything. A PARTIAL
-    // failure (some entries embedded, one write degraded) still attempts —
-    // and if the endpoint is genuinely down, the failure surfaces as a live
-    // `semanticWarning` below instead of silently skipping with no signal.
+        return Promise.resolve({ neighbors: null });
+    // A real-time completeness fact, not a cached verdict: skip the round trip
+    // only when the index has never embedded anything. A PARTIAL failure still
+    // attempts — and if the endpoint is genuinely down, the failure surfaces as
+    // a live warning instead of silently skipping with no signal.
     if (getEmbeddingCount(db) === 0)
-        return { scores: null };
-    try {
-        const { embed } = await import("../../llm/embedder.js");
-        const queryEmbedding = await embed(query, config.embedding);
-        const vecResults = searchVec(db, queryEmbedding, k);
-        const scores = new Map();
-        for (const { id, distance } of vecResults) {
-            // Convert L2 distance to cosine similarity (vectors are normalized).
-            // Guard against NaN/Infinity from sqlite-vec edge cases.
-            const raw = 1 - (distance * distance) / 2;
-            scores.set(id, Number.isFinite(raw) ? Math.max(0, raw) : 0);
-        }
-        return { scores };
-    }
-    catch (error) {
-        return { scores: null, warning: buildVectorFallbackWarning(config, error) };
-    }
+        return Promise.resolve({ neighbors: null });
+    const timeoutMs = config.embedding?.queryTimeoutMs ?? DEFAULT_QUERY_EMBED_TIMEOUT_MS;
+    const controller = new AbortController();
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            controller.abort();
+            reject(new Error(`Query embedding timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+    });
+    const queryText = applyEmbeddingTemplate(resolveEmbeddingProfile(config.embedding).queryTemplate, query);
+    return Promise.race([embed(queryText, config.embedding, controller.signal), timeout])
+        .then((vector) => ({ neighbors: searchVec(db, vector, CHANNEL_DEPTH) }))
+        .catch((error) => ({ neighbors: null, warning: buildVectorFallbackWarning(config, error) }))
+        .finally(() => clearTimeout(timer));
 }
 function buildVectorFallbackWarning(config, error) {
     const endpoint = safeEmbeddingEndpoint(config);
@@ -770,99 +514,39 @@ function classifyVectorFailure(error) {
 }
 // ── Hit building ────────────────────────────────────────────────────────────
 export async function buildDbHit(input) {
-    const rendererRegistry = input.rendererRegistry ?? defaultRendererRegistry;
     const absolutePath = path.resolve(input.path);
-    const entryStashDir = findSourceForPath(absolutePath, input.sources)?.path ?? input.defaultStashDir;
-    // Quality and confidence boosts are now applied in the main scoring
-    // phase (searchDatabase). buildDbHit receives the already-final score and
-    // passes it through without further multiplication. We still compute the
-    // boost values here for buildWhyMatched reporting.
-    // Mirrors the boost computation in `searchDatabase`; only `curated`
-    // contributes a positive boost. Used for `whyMatched` reporting only.
-    const qualityBoost = input.entry.quality === "curated" ? 0.05 : 0;
-    const confidenceBoost = typeof input.entry.confidence === "number" ? Math.min(0.05, Math.max(0, input.entry.confidence) * 0.05) : 0;
-    // Round to 4 decimal places, no boost multiplication
-    const score = Math.round(input.score * 10000) / 10000;
-    const graphBoost = getSearchHitAttribution(input.attributionSource ?? {})?.graphExtraction?.boost ?? 0;
-    const whyMatched = buildWhyMatched(input.entry, input.query, input.rankingMode, qualityBoost, confidenceBoost, input.utilityBoosted, graphBoost, input.lexicalMatch);
-    const graphHit = input.graphContext ? collectGraphRelatedHit(input.graphContext, absolutePath) : null;
     const source = findSourceForPath(absolutePath, input.sources);
+    const entryStashDir = source?.path ?? input.defaultStashDir;
     const defaultBundleId = input.config?.defaultBundle ??
         (source && path.resolve(source.path) === path.resolve(input.defaultStashDir)
             ? (input.bundleId ?? undefined)
             : undefined);
-    const parentRef = resolveSearchHitRef(input.entry, input, defaultBundleId);
-    // Fragments prove lexical relevance, but executable assets must retain the
-    // parent ref consumed by their advertised action (for example workflow run).
-    // The central type-presentation contract opts those types out explicitly.
-    const ref = input.fragmentId && allowsFragmentRef(input.entry.type) ? `${parentRef}#${input.fragmentId}` : parentRef;
+    const ref = resolveSearchHitRef(input.entry, input, defaultBundleId);
     const editable = isEditable(absolutePath, input.config, input.sources);
-    const indexedFragment = input.indexedFragment === undefined
-        ? input.fragmentId && input.db
-            ? getIndexedMarkdownFragment(input.db, input.itemRef, input.fragmentId)
-            : undefined
-        : (input.indexedFragment ?? undefined);
-    const selectedRef = input.fragmentId && ref !== parentRef ? `${parentRef}#${input.fragmentId}` : undefined;
-    const parentEstimatedTokens = typeof input.entry.fileSize === "number"
-        ? Math.round(input.entry.fileSize / 4)
-        : indexedFragment
-            ? Math.round(indexedFragment.parentChars / 4)
-            : undefined;
-    const fragmentEstimatedTokens = indexedFragment ? Math.round(indexedFragment.fragmentChars / 4) : undefined;
-    const estimatedTokens = selectedRef === ref && fragmentEstimatedTokens !== undefined ? fragmentEstimatedTokens : parentEstimatedTokens;
+    const estimatedTokens = typeof input.entry.fileSize === "number" ? Math.round(input.entry.fileSize / 4) : undefined;
     const hit = {
         type: input.entry.type,
         name: input.entry.name,
         path: absolutePath,
         ref,
-        origin: resolveSearchHitOrigin(source),
+        origin: source?.registryId ?? null,
         editable,
         ...(!editable ? { editHint: buildEditHint(ref) } : {}),
         description: input.entry.description,
         tags: input.entry.tags,
         size: deriveSize(input.entry.fileSize),
-        action: buildLocalAction(input.entry.type, ref, rendererRegistry),
-        score,
-        whyMatched,
+        action: buildLocalAction(input.entry.type, ref),
+        score: input.score,
+        ...(input.whyMatched ? { whyMatched: input.whyMatched } : {}),
         ...(estimatedTokens !== undefined ? { estimatedTokens } : {}),
-        ...(selectedRef
-            ? {
-                selectedRef,
-                parentRef,
-                ...(indexedFragment
-                    ? {
-                        fragmentOrdinal: indexedFragment.ordinal + 1,
-                        fragmentCount: indexedFragment.count,
-                        startLine: indexedFragment.startLine,
-                        endLine: indexedFragment.endLine,
-                        ...(indexedFragment.previousFragmentId
-                            ? { previousRef: `${parentRef}#${indexedFragment.previousFragmentId}` }
-                            : {}),
-                        ...(indexedFragment.nextFragmentId
-                            ? { nextRef: `${parentRef}#${indexedFragment.nextFragmentId}` }
-                            : {}),
-                        fragmentChars: indexedFragment.fragmentChars,
-                        fragmentEstimatedTokens,
-                        parentChars: indexedFragment.parentChars,
-                        ...(parentEstimatedTokens !== undefined ? { parentEstimatedTokens } : {}),
-                    }
-                    : parentEstimatedTokens !== undefined
-                        ? { parentEstimatedTokens }
-                        : {}),
-            }
-            : {}),
         // 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 } } : {}),
-        // Which stage of the progressive AND->OR lexical ladder produced this
-        // hit. Omitted when the hit has no FTS component (pure-semantic hybrid
-        // contribution).
-        ...(input.lexicalMatch ? { matchStage: input.lexicalMatch } : {}),
     };
-    attachDbHitAttribution(hit, input);
+    if (input.entry.content)
+        hitContent.set(hit, input.entry.content);
     if (input.entry.derivedFrom) {
         attachSearchHitAttribution(hit, {
             memoryInference: { exposure: "direct" },
@@ -872,90 +556,10 @@ export async function buildDbHit(input) {
         type: input.entry.type,
         stashDir: entryStashDir,
         bundleId: input.bundleId,
-        rendererRegistry,
         db: input.db,
     });
     return hit;
 }
-function attachDbHitAttribution(hit, input) {
-    if (input.lexicalMatch) {
-        attachSearchHitAttribution(hit, {
-            lexical: {
-                execution: input.lexicalMatch,
-                nameMatchTier: lexicalNameMatchTier(input.entry, buildLexicalQueryPlan(input.query).tokens),
-            },
-        });
-    }
-    if (input.attributionSource)
-        copySearchHitAttribution(input.attributionSource, hit);
-}
-export function buildWhyMatched(entry, query, 
-// "hybrid" ranking mode
-rankingMode, qualityBoost, confidenceBoost, utilityBoosted, graphBoost, lexicalMatch) {
-    const reasons = [
-        rankingMode === "hybrid"
-            ? "hybrid (fts + semantic)"
-            : rankingMode === "semantic"
-                ? "semantic similarity"
-                : "fts bm25 relevance",
-    ];
-    if (lexicalMatch === "relaxed")
-        reasons.push("lexical recovery after strict query returned no hits");
-    if (lexicalMatch === "prefix")
-        reasons.push("prefix match after strict query returned no hits");
-    const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
-    const queryLower = query.toLowerCase().trim();
-    const name = entry.name.toLowerCase();
-    const nameBase = name.split("/").pop() ?? name;
-    const tags = entry.tags?.join(" ").toLowerCase() ?? "";
-    const searchHints = entry.searchHints?.join(" ").toLowerCase() ?? "";
-    const aliases = entry.aliases?.join(" ").toLowerCase() ?? "";
-    const desc = entry.description?.toLowerCase() ?? "";
-    // Name match quality
-    if (nameBase === queryLower || name === queryLower) {
-        reasons.push("exact name match");
-    }
-    else if (nameBase.includes(queryLower) || queryLower.includes(nameBase)) {
-        reasons.push("near-exact name match");
-    }
-    else if (tokens.some((t) => nameBase.includes(t))) {
-        reasons.push("matched name tokens");
-    }
-    // Type relevance
-    if (entry.type === "skill" || entry.type === "command" || entry.type === "agent") {
-        reasons.push(`${entry.type} type boost`);
-    }
-    if (tokens.some((t) => tags.includes(t)))
-        reasons.push("matched tags");
-    if (tokens.some((t) => searchHints.includes(t)))
-        reasons.push("matched searchHints");
-    if (tokens.some((t) => aliases.includes(t)))
-        reasons.push("matched aliases");
-    if (tokens.some((t) => desc.includes(t)))
-        reasons.push("matched description");
-    if (qualityBoost > 0)
-        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 === "asserted")
-        reasons.push("asserted belief state");
-    if (entry.beliefState === "contradicted")
-        reasons.push("contradicted belief state");
-    if (entry.beliefState === "superseded")
-        reasons.push("superseded belief state");
-    if (entry.beliefState === "deprecated")
-        reasons.push("deprecated belief state");
-    if (entry.beliefState === "archived")
-        reasons.push("archived belief state");
-    if (utilityBoosted)
-        reasons.push("usage history boost");
-    if (typeof graphBoost === "number" && graphBoost > 0) {
-        reasons.push(`graph boost +${graphBoost.toFixed(2)}`);
-    }
-    return reasons;
-}
 // ── Utilities ────────────────────────────────────────────────────────────────
 export function deriveSize(bytes) {
     if (bytes === undefined)
@@ -966,11 +570,7 @@ export function deriveSize(bytes) {
         return "medium";
     return "large";
 }
-/**
- * Deduplicate the already-ranked result stream by file path. The caller owns
- * the one ranking order; re-sorting here would silently discard exact-name and
- * relaxed-recovery ordering in favor of an internal pre-clamp score.
- */
+/** Keep the first entry per file path; the caller owns the order. */
 function deduplicateByPath(items) {
     const seen = new Set();
     return items.filter((item) => {