akm-cli 0.7.4 → 0.8.0-rc.10

package/dist/indexer/db-search.js

@@ -1,37 +1,24 @@
-/**
- * Database-backed (SQLite + FTS5/vector) source search implementation.
- *
- * 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.
- */
+// This Source Code Form is subject to the terms of the Mozilla Public
+// 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/.
 import fs from "node:fs";
-import path from "node:path";
+import { buildActionFromContributors, defaultActionContributors } from "../core/action-contributors";
 import { makeAssetRef } from "../core/asset-ref";
 import { defaultRendererRegistry } from "../core/asset-registry";
-import { deriveCanonicalAssetNameFromStashRoot } from "../core/asset-spec";
 import { getDbPath } from "../core/paths";
 import { warn } from "../core/warn";
-import { closeDatabase, getAllEntries, getEntryById, getEntryCount, getMeta, getUtilityScoresByIds, openExistingDatabase, sanitizeFtsQuery, searchFts, searchVec, } from "./db";
-import { getRenderer } from "./file-context";
-import { computeGraphBoost, loadGraphBoostContext } from "./graph-boost";
-import { generateMetadataFlat, isProposedQuality, loadStashFile, shouldIndexStashFile, } from "./metadata";
-import { buildSearchText } from "./search-fields";
+import { getCurrentWorkflowScopeKey } from "../workflows/scope-key";
+import { closeDatabase, getAllEntries, getEntryById, getEntryCount, getMeta, getPositiveFeedbackCountsByIds, openExistingDatabase, sanitizeFtsQuery, searchFts, searchVec, } from "./db";
+import { ensureIndex } from "./ensure-index";
+import { collectGraphRelatedHit, computeGraphBoost, loadGraphBoostContext, } from "./graph-boost";
+import { isProposedQuality } from "./metadata";
+import { resolveProjectContext } from "./project-context";
+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";
-import { walkStashFlat } from "./walker";
-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) {
@@ -42,81 +29,97 @@ function resolveSearchHitRef(entry, refName, source) {
 function resolveSearchHitOrigin(source) {
     return source?.wikiName ? null : (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 ───────────────────────────────────────────────────
 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 rendererRegistry = input.rendererRegistry ?? defaultRendererRegistry;
     const allSourceDirs = sources.map((s) => s.path);
     const rawStatus = readSemanticStatus();
     const semanticStatus = getEffectiveSemanticStatus(config, rawStatus);
     const warnings = [];
     if (config.semanticSearchMode === "auto" && semanticStatus === "pending") {
-        // Distinguish between fingerprint mismatch (config changed) and never-set-up.
         const currentFingerprint = deriveSemanticProviderFingerprint(config.embedding);
         if (rawStatus && rawStatus.providerFingerprint !== currentFingerprint) {
             warnings.push("Embedding config changed. Run 'akm index --full' to rebuild the semantic index with the new provider.");
         }
+        else if (!config.embedding?.endpoint || !config.embedding?.model) {
+            // #480: when semantic mode is `auto` but no embedding provider is
+            // configured (e.g. `akm setup --yes` ran without picking one), telling
+            // the user to "run akm setup" is misleading — they just did. Surface
+            // the actual remediation: configure an embedding endpoint OR switch
+            // semanticSearchMode to `off` to silence the warning.
+            warnings.push("Semantic search is enabled (semanticSearchMode='auto') but no embedding provider is configured. " +
+                'Either: (a) `akm config set embedding \'{"endpoint":"...","model":"..."}\'`, or ' +
+                "(b) `akm config set semanticSearchMode off` to use keyword-only search.");
+        }
         else {
-            warnings.push("Semantic search is pending verification. Run 'akm setup' or 'akm index --full' to enable semantic search.");
+            warnings.push("Semantic search is pending verification. Run 'akm index --full' to build the semantic index now, or wait for the next background index pass.");
         }
     }
     if (config.semanticSearchMode === "auto" && semanticStatus === "blocked") {
         warnings.push("Semantic search is currently blocked. Using keyword search until the semantic backend is healthy again.");
     }
-    // Try to open the database
+    // Auto-index when stale so the DB is always current before querying.
+    await ensureIndex(stashDir);
     const dbPath = getDbPath();
+    if (!fs.existsSync(dbPath)) {
+        return {
+            hits: [],
+            tip: "No search index available. Run 'akm index' to build one.",
+            warnings: warnings.length > 0 ? warnings : undefined,
+            mode: "keyword",
+        };
+    }
+    const db = openExistingDatabase(dbPath);
     try {
-        if (fs.existsSync(dbPath)) {
-            const db = openExistingDatabase(dbPath);
-            try {
-                const entryCount = getEntryCount(db);
-                const storedStashDir = getMeta(db, "stashDir");
-                // Accept the index if the incoming stashDir matches the primary OR
-                // appears anywhere in the stored stashDirs array. This prevents
-                // unnecessary substring fallback when only the primary dir changes.
-                let stashDirMatch = storedStashDir === stashDir;
-                if (!stashDirMatch) {
-                    try {
-                        const storedDirs = JSON.parse(getMeta(db, "stashDirs") ?? "[]");
-                        stashDirMatch = storedDirs.includes(stashDir);
-                    }
-                    catch {
-                        /* ignore malformed stashDirs */
-                    }
-                }
-                if (entryCount > 0 && stashDirMatch) {
-                    const { hits, embedMs, rankMs } = await searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry, filters, includeProposed);
-                    return {
-                        hits,
-                        tip: hits.length === 0
-                            ? "No matching stash assets were found. Try running 'akm index' to rebuild."
-                            : undefined,
-                        warnings: warnings.length > 0 ? warnings : undefined,
-                        embedMs,
-                        rankMs,
-                    };
-                }
-            }
-            finally {
-                closeDatabase(db);
-            }
+        const entryCount = getEntryCount(db);
+        if (entryCount === 0) {
+            return {
+                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, beliefFilter, restrictToSources);
+        return {
+            hits,
+            tip: hits.length === 0
+                ? "No matching stash assets were found. Try a different query or run 'akm index' to rebuild."
+                : undefined,
+            warnings: warnings.length > 0 ? warnings : undefined,
+            embedMs,
+            rankMs,
+            mode: embedMs !== undefined && embedMs > 0 ? "semantic" : "keyword",
+        };
     }
-    catch (error) {
-        warn("Search index unavailable, falling back to substring search:", error instanceof Error ? error.message : String(error));
+    finally {
+        closeDatabase(db);
     }
-    const hitArrays = await Promise.all(allSourceDirs.map((dir) => substringSearch(query, searchType, limit, dir, sources, config, rendererRegistry, filters, includeProposed)));
-    const hits = hitArrays.flat().slice(0, limit);
-    return {
-        hits,
-        tip: hits.length === 0 ? "No matching stash assets were found. Try running 'akm index' to rebuild." : undefined,
-        warnings: warnings.length > 0 ? warnings : undefined,
-    };
 }
 // ── 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", restrictToSources = false) {
     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
@@ -132,18 +135,26 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
             seenFilePaths.add(ie.filePath);
             return true;
         });
+        // Source filter: when the caller narrowed `sources` via `--source <name>`,
+        // drop entries whose filePath does not live under any of the requested
+        // sources. The FTS index spans every configured source, so without this
+        // filter a narrowed --source request would still leak results.
+        const sourceFiltered = restrictToSources
+            ? uniqueEntries.filter((ie) => findSourceForPath(ie.filePath, sources) !== undefined)
+            : uniqueEntries;
         // Scope filter: drop entries whose stored scope does not satisfy every
         // supplied scope key. Filtering happens BEFORE the limit slice so a
         // restrictive filter still returns up to `limit` results.
         const scopeFiltered = filters
-            ? uniqueEntries.filter((ie) => entryMatchesScope(ie.entry.scope, filters))
-            : uniqueEntries;
+            ? sourceFiltered.filter((ie) => entryMatchesScope(ie.entry.scope, filters))
+            : sourceFiltered;
         // Proposed-quality filter (v1 spec §4.2): exclude entries with
         // `quality: "proposed"` unless the caller explicitly opts in.
         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,
@@ -155,6 +166,7 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
             sources,
             config,
             rendererRegistry,
+            db,
         })));
         return { hits };
     }
@@ -170,22 +182,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) {
@@ -194,46 +191,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).
@@ -242,8 +205,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
@@ -256,170 +217,48 @@ 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;
-        }
+    // 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 has set AKM_DISABLE_PROJECT_CONTEXT=1.
+    const projectContext = process.env.AKM_DISABLE_PROJECT_CONTEXT === "1" ? 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(db, scored.map((item) => item.id))
+        : undefined;
+    // Resolve per-project scope key for scoped utility scoring.
+    // AKM_DISABLE_SCOPED_UTILITY=1 opts out (e.g. for registry searches or tests).
+    let scopeKey;
+    try {
+        scopeKey = process.env.AKM_DISABLE_SCOPED_UTILITY === "1" ? undefined : getCurrentWorkflowScopeKey();
     }
+    catch {
+        // Non-fatal — ranking proceeds without scoped utility on any error.
+    }
+    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.
@@ -433,18 +272,29 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
     // a filename field all collapse to files[0]). Showing the same path/ref
     // multiple times clutters results.
     const deduped = deduplicateByPath(preFilter);
+    // Source filter: when the caller narrowed `sources` via `--source <name>`,
+    // drop hits whose filePath does not live under any of the requested
+    // sources. The FTS/vector index spans every configured source, so without
+    // this filter a narrowed --source request would still leak results from
+    // other sources that happened to match the query text.
+    const sourceFiltered = restrictToSources
+        ? deduped.filter((item) => findSourceForPath(item.filePath, sources) !== undefined)
+        : deduped;
     // Scope filter: drop hits whose stored scope does not satisfy every supplied
     // key. Applied AFTER ranking — filtering narrows the result set without
     // touching the single FTS5+boosts scoring pipeline.
-    const scopeFiltered = filters ? deduped.filter((item) => entryMatchesScope(item.entry.scope, filters)) : deduped;
+    const scopeFiltered = filters
+        ? sourceFiltered.filter((item) => entryMatchesScope(item.entry.scope, filters))
+        : sourceFiltered;
     // Proposed-quality filter (v1 spec §4.2): exclude entries with
     // `quality: "proposed"` unless the caller passed `--include-proposed`.
     // Applied AFTER ranking for the same reason as scope filtering.
     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
@@ -463,11 +313,29 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
             sources,
             config,
             utilityBoosted,
+            graphContext,
             rendererRegistry,
+            db,
         });
     }));
     return { embedMs, rankMs, hits };
 }
+function matchBeliefFilter(type, beliefState, filter) {
+    if (filter === "all")
+        return true;
+    if (type !== "memory")
+        return true;
+    if (filter === "current") {
+        // Phase 1A: `asserted` is a "current" state (stronger authority than `active`);
+        // `deprecated` is excluded from current results.
+        return beliefState === undefined || beliefState === "active" || beliefState === "asserted";
+    }
+    // historical
+    return (beliefState === "contradicted" ||
+        beliefState === "superseded" ||
+        beliefState === "deprecated" ||
+        beliefState === "archived");
+}
 // ── Vector scorer ───────────────────────────────────────────────────────────
 async function tryVecScores(db, query, k, config) {
     const semanticStatus = getEffectiveSemanticStatus(config, readSemanticStatus());
@@ -494,62 +362,10 @@ async function tryVecScores(db, query, k, config) {
         return null;
     }
 }
-// ── Substring fallback (no index) ───────────────────────────────────────────
-async function substringSearch(query, searchType, limit, stashDir, sources, config, rendererRegistry = defaultRendererRegistry, filters, includeProposed = false) {
-    const assets = await indexAssets(stashDir, searchType, sources);
-    const scopeMatched = filters ? assets.filter((asset) => entryMatchesScope(asset.entry.scope, filters)) : assets;
-    const qualityMatched = includeProposed
-        ? scopeMatched
-        : scopeMatched.filter((asset) => !isProposedQuality(asset.entry.quality));
-    const matched = qualityMatched.filter((asset) => !query || buildSearchText(asset.entry).includes(query));
-    if (!query) {
-        const sorted = matched.sort(compareAssets);
-        const unique = deduplicateAssetsByPath(sorted);
-        return Promise.all(unique
-            .slice(0, limit)
-            .map((asset) => assetToSearchHit(asset, stashDir, sources, config, undefined, rendererRegistry)));
-    }
-    // Score and sort by relevance
-    const scored = matched.map((asset) => ({ asset, score: scoreSubstringMatch(asset.entry, query) }));
-    scored.sort((a, b) => b.score - a.score || compareAssets(a.asset, b.asset));
-    // Deduplicate by path — keep highest-scored entry per file
-    const dedupedScored = deduplicateByPath(scored.map((s) => ({ ...s, filePath: s.asset.path })));
-    return Promise.all(dedupedScored
-        .slice(0, limit)
-        .map(({ asset, score }) => assetToSearchHit(asset, stashDir, sources, config, score, rendererRegistry)));
-}
-function scoreSubstringMatch(entry, query) {
-    const tokens = query.split(/\s+/).filter(Boolean);
-    if (tokens.length === 0)
-        return 0.5;
-    let score = 0.3;
-    const nameLower = entry.name.toLowerCase().replace(/[-_]/g, " ");
-    const descLower = (entry.description ?? "").toLowerCase();
-    const tagsLower = (entry.tags ?? []).join(" ").toLowerCase();
-    if (nameLower === query) {
-        score += 0.5;
-    }
-    else if (nameLower.includes(query)) {
-        score += 0.35;
-    }
-    else if (tokens.some((t) => nameLower.includes(t))) {
-        score += 0.2;
-    }
-    if (tokens.some((t) => tagsLower.includes(t))) {
-        score += 0.1;
-    }
-    if (tokens.some((t) => descLower.includes(t))) {
-        score += 0.05;
-    }
-    // Issue #8: round to 4 decimal places instead of 2
-    return Math.round(Math.min(1, score) * 10000) / 10000;
-}
 // ── Hit building ────────────────────────────────────────────────────────────
 export async function buildDbHit(input) {
     const rendererRegistry = input.rendererRegistry ?? defaultRendererRegistry;
     const entryStashDir = findSourceForPath(input.path, input.sources)?.path ?? input.defaultStashDir;
-    const canonical = deriveCanonicalAssetNameFromStashRoot(input.entry.type, entryStashDir, input.path);
-    const refName = canonical && !canonical.startsWith("../") && !canonical.startsWith("..\\") ? canonical : input.entry.name;
     // 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
@@ -560,9 +376,11 @@ export async function buildDbHit(input) {
     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 whyMatched = buildWhyMatched(input.entry, input.query, input.rankingMode, qualityBoost, confidenceBoost, input.utilityBoosted);
+    const graphBoost = input.graphContext ? computeGraphBoost(input.graphContext, input.path) : 0;
+    const whyMatched = buildWhyMatched(input.entry, input.query, input.rankingMode, qualityBoost, confidenceBoost, input.utilityBoosted, graphBoost);
+    const graphHit = input.graphContext ? collectGraphRelatedHit(input.graphContext, input.path) : null;
     const source = findSourceForPath(input.path, input.sources);
-    const ref = resolveSearchHitRef(input.entry, refName, source);
+    const ref = resolveSearchHitRef(input.entry, input.entry.name, source);
     const editable = isEditable(input.path, input.config);
     const estimatedTokens = typeof input.entry.fileSize === "number" ? Math.round(input.entry.fileSize / 4) : undefined;
     const hit = {
@@ -572,7 +390,9 @@ export async function buildDbHit(input) {
         ref,
         origin: resolveSearchHitOrigin(source),
         editable,
-        ...(!editable ? { editHint: buildEditHint(input.path, input.entry.type, refName, source?.registryId) } : {}),
+        ...(!editable
+            ? { editHint: buildEditHint(input.path, input.entry.type, input.entry.name, source?.registryId) }
+            : {}),
         description: input.entry.description,
         tags: input.entry.tags,
         size: deriveSize(input.entry.fileSize),
@@ -583,16 +403,21 @@ 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,
+        db: input.db,
+    });
     return hit;
 }
 export function buildWhyMatched(entry, query, 
 // "hybrid" ranking mode
-rankingMode, qualityBoost, confidenceBoost, utilityBoosted) {
+rankingMode, qualityBoost, confidenceBoost, utilityBoosted, graphBoost) {
     const reasons = [
         rankingMode === "hybrid"
             ? "hybrid (fts + semantic)"
@@ -634,40 +459,24 @@ 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 === "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");
-    return reasons;
-}
-async function assetToSearchHit(asset, stashDir, sources, config, score, rendererRegistry = defaultRendererRegistry) {
-    const source = findSourceForPath(asset.path, sources);
-    const editable = isEditable(asset.path, config);
-    const ref = resolveSearchHitRef(asset.entry, asset.entry.name, source);
-    const fileSize = readFileSize(asset.path);
-    const size = deriveSize(fileSize);
-    const estimatedTokens = typeof fileSize === "number" ? Math.round(fileSize / 4) : undefined;
-    const hit = {
-        type: asset.entry.type,
-        name: asset.entry.name,
-        path: asset.path,
-        ref,
-        origin: resolveSearchHitOrigin(source),
-        editable,
-        ...(!editable
-            ? { editHint: buildEditHint(asset.path, asset.entry.type, asset.entry.name, source?.registryId) }
-            : {}),
-        description: asset.entry.description,
-        tags: asset.entry.tags,
-        ...(size ? { size } : {}),
-        action: buildLocalAction(asset.entry.type, ref, rendererRegistry),
-        ...(score !== undefined ? { score } : {}),
-        ...(estimatedTokens !== undefined ? { estimatedTokens } : {}),
-        ...(asset.entry.quality ? { quality: asset.entry.quality } : {}),
-    };
-    const renderer = await rendererForType(asset.entry.type, rendererRegistry);
-    if (renderer?.enrichSearchHit) {
-        renderer.enrichSearchHit(hit, stashDir);
+    if (typeof graphBoost === "number" && graphBoost > 0) {
+        reasons.push(`graph boost +${graphBoost.toFixed(2)}`);
     }
-    return hit;
+    return reasons;
 }
 // ── Utilities ────────────────────────────────────────────────────────────────
 export function deriveSize(bytes) {
@@ -679,93 +488,13 @@ export function deriveSize(bytes) {
         return "medium";
     return "large";
 }
-function readFileSize(filePath) {
-    try {
-        return fs.statSync(filePath).size;
-    }
-    catch {
-        return undefined;
-    }
-}
-async function indexAssets(stashDir, type, sources) {
-    const resolvedStashDir = realpathOrResolve(stashDir);
-    const source = sources?.find((entry) => realpathOrResolve(entry.path) === resolvedStashDir);
-    if (source?.wikiName) {
-        return indexWikiRootAssets(stashDir, source.wikiName, type);
-    }
-    const assets = [];
-    const filterType = type === "any" ? undefined : type;
-    const fileContexts = walkStashFlat(stashDir);
-    const dirGroups = new Map();
-    for (const ctx of fileContexts) {
-        const group = dirGroups.get(ctx.parentDirAbs);
-        if (group)
-            group.push(ctx.absPath);
-        else
-            dirGroups.set(ctx.parentDirAbs, [ctx.absPath]);
-    }
-    for (const [dirPath, files] of dirGroups) {
-        const generated = await generateMetadataFlat(stashDir, files);
-        const legacyOverrides = loadStashFile(dirPath, { requireFilename: true });
-        const mergedEntries = legacyOverrides
-            ? generated.entries.map((entry) => mergeLegacyEntry(entry, legacyOverrides.entries))
-            : generated.entries;
-        const stash = mergedEntries.length > 0 ? { entries: mergedEntries } : legacyOverrides;
-        if (!stash || stash.entries.length === 0)
-            continue;
-        for (const entry of stash.entries) {
-            if (filterType && entry.type !== filterType)
-                continue;
-            if (!entry.filename)
-                continue;
-            const entryPath = path.join(dirPath, entry.filename);
-            if (!shouldIndexStashFile(stashDir, entryPath))
-                continue;
-            assets.push({ entry, path: entryPath });
-        }
-    }
-    return assets;
-}
-function mergeLegacyEntry(entry, legacyEntries) {
-    const legacy = legacyEntries.find((candidate) => candidate.filename === entry.filename);
-    return legacy ? { ...entry, ...legacy, filename: entry.filename } : entry;
-}
-async function indexWikiRootAssets(wikiRoot, wikiName, type) {
-    if (type !== "any" && type !== "wiki")
-        return [];
-    const assets = [];
-    for (const ctx of walkStashFlat(wikiRoot)) {
-        if (ctx.ext !== ".md")
-            continue;
-        if (!shouldIndexStashFile(wikiRoot, ctx.absPath, { treatStashRootAsWikiRoot: true }))
-            continue;
-        const relNoExt = ctx.relPath.replace(/\.md$/, "");
-        assets.push({
-            entry: {
-                name: `${wikiName}/${relNoExt}`,
-                type: "wiki",
-                filename: ctx.fileName,
-                description: ctx.frontmatter()?.description,
-                source: "frontmatter",
-            },
-            path: ctx.absPath,
-        });
-    }
-    return assets;
-}
-function compareAssets(a, b) {
-    if (a.entry.type !== b.entry.type)
-        return a.entry.type.localeCompare(b.entry.type);
-    return a.entry.name.localeCompare(b.entry.name);
-}
 /**
  * Deduplicate scored results by file path, keeping only the highest-scored
  * entry per unique path. Sorts by score descending internally to ensure the
  * precondition is always met regardless of caller.
  */
 function deduplicateByPath(items) {
-    // Sort inside to enforce the descending-score precondition
-    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))
@@ -774,18 +503,6 @@ function deduplicateByPath(items) {
         return true;
     });
 }
-/**
- * Deduplicate IndexedAsset[] by path, keeping the first (highest-priority) entry.
- */
-function deduplicateAssetsByPath(assets) {
-    const seen = new Set();
-    return assets.filter((asset) => {
-        if (seen.has(asset.path))
-            return false;
-        seen.add(asset.path);
-        return true;
-    });
-}
 /**
  * Exact-match scope filter check. Legacy entries without a `scope` object only
  * match when no filter is supplied — which is what the caller guards on
@@ -801,11 +518,3 @@ function entryMatchesScope(scope, filters) {
     }
     return true;
 }
-function realpathOrResolve(targetPath) {
-    try {
-        return fs.realpathSync(targetPath);
-    }
-    catch {
-        return path.resolve(targetPath);
-    }
-}