akm-cli 0.6.1 → 0.7.0

package/dist/{indexer → src/indexer}/db-search.js

@@ -19,7 +19,8 @@ import { getDbPath } from "../core/paths";
 import { warn } from "../core/warn";
 import { closeDatabase, getAllEntries, getEntryById, getEntryCount, getMeta, getUtilityScoresByIds, openDatabase, sanitizeFtsQuery, searchFts, searchVec, } from "./db";
 import { getRenderer } from "./file-context";
-import { generateMetadataFlat, loadStashFile, shouldIndexStashFile } from "./metadata";
+import { computeGraphBoost, loadGraphBoostContext } from "./graph-boost";
+import { generateMetadataFlat, isProposedQuality, loadStashFile, shouldIndexStashFile, } from "./metadata";
 import { buildSearchText } from "./search-fields";
 import { buildEditHint, findSourceForPath, isEditable } from "./search-source";
 import { deriveSemanticProviderFingerprint, getEffectiveSemanticStatus, isSemanticRuntimeReady, readSemanticStatus, } from "./semantic-status";
@@ -44,6 +45,8 @@ function resolveSearchHitOrigin(source) {
 // ── 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 rendererRegistry = input.rendererRegistry ?? defaultRendererRegistry;
     const allSourceDirs = sources.map((s) => s.path);
     const rawStatus = readSemanticStatus();
@@ -85,7 +88,7 @@ export async function searchLocal(input) {
                     }
                 }
                 if (entryCount > 0 && stashDirMatch) {
-                    const { hits, embedMs, rankMs } = await searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry);
+                    const { hits, embedMs, rankMs } = await searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry, filters, includeProposed);
                     return {
                         hits,
                         tip: hits.length === 0
@@ -105,7 +108,7 @@ export async function searchLocal(input) {
     catch (error) {
         warn("Search index unavailable, falling back to substring search:", error instanceof Error ? error.message : String(error));
     }
-    const hitArrays = await Promise.all(allSourceDirs.map((dir) => substringSearch(query, searchType, limit, dir, sources, config, rendererRegistry)));
+    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,
@@ -114,7 +117,7 @@ export async function searchLocal(input) {
     };
 }
 // ── Database search ─────────────────────────────────────────────────────────
-async function searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry = defaultRendererRegistry) {
+async function searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry = defaultRendererRegistry, filters, includeProposed = 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
@@ -130,7 +133,18 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
             seenFilePaths.add(ie.filePath);
             return true;
         });
-        const selected = uniqueEntries.slice(0, limit);
+        // 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;
+        // 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 hits = await Promise.all(selected.map((ie) => buildDbHit({
             entry: ie.entry,
             path: ie.filePath,
@@ -231,6 +245,23 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
     // 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
+    // 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.
+        const primaryDir = allSourceDirs[0];
+        if (!primaryDir)
+            return null;
+        return loadGraphBoostContext(primaryDir, query);
+    })();
     for (const item of scored) {
         const entry = item.entry;
         let boostSum = 0;
@@ -263,6 +294,7 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
         const TYPE_BOOST = {
             skill: 0.4,
             command: 0.35,
+            workflow: 0.35,
             agent: 0.3,
             script: 0.2,
             memory: 0.1,
@@ -324,10 +356,26 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
             }
         }
         // ── 7. Metadata quality signals ──
-        const qualityBoost = entry.quality === "generated" ? 0 : 0.05;
+        // 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);
     }
@@ -371,22 +419,39 @@ 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);
+    // 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;
+    // 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 rankMs = Date.now() - tRank0;
-    const selected = deduped.slice(0, limit);
-    const hits = await Promise.all(selected.map(({ entry, filePath, score, rankingMode, utilityBoosted }) => buildDbHit({
-        entry,
-        path: filePath,
-        // Round to 4 decimal places
-        score: Math.round(score * 10000) / 10000,
-        query,
-        rankingMode,
-        defaultStashDir: stashDir,
-        allSourceDirs,
-        sources,
-        config,
-        utilityBoosted,
-        rendererRegistry,
-    })));
+    const selected = qualityFiltered.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
+        // — up to ~1.05 additive contribution — made detectable); clamp here
+        // so the score handed to buildDbHit always satisfies the spec.
+        const finalScore = Math.min(1, Math.max(0, score));
+        return buildDbHit({
+            entry,
+            path: filePath,
+            // Round to 4 decimal places
+            score: Math.round(finalScore * 10000) / 10000,
+            query,
+            rankingMode,
+            defaultStashDir: stashDir,
+            allSourceDirs,
+            sources,
+            config,
+            utilityBoosted,
+            rendererRegistry,
+        });
+    }));
     return { embedMs, rankMs, hits };
 }
 // ── Vector scorer ───────────────────────────────────────────────────────────
@@ -416,9 +481,13 @@ async function tryVecScores(db, query, k, config) {
     }
 }
 // ── Substring fallback (no index) ───────────────────────────────────────────
-async function substringSearch(query, searchType, limit, stashDir, sources, config, rendererRegistry = defaultRendererRegistry) {
+async function substringSearch(query, searchType, limit, stashDir, sources, config, rendererRegistry = defaultRendererRegistry, filters, includeProposed = false) {
     const assets = await indexAssets(stashDir, searchType, sources);
-    const matched = assets.filter((asset) => !query || buildSearchText(asset.entry).includes(query));
+    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);
@@ -471,7 +540,9 @@ export async function buildDbHit(input) {
     // 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.
-    const qualityBoost = input.entry.quality === "generated" ? 0 : 0.05;
+    // 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;
@@ -495,6 +566,9 @@ export async function buildDbHit(input) {
         score,
         whyMatched,
         ...(estimatedTokens !== undefined ? { estimatedTokens } : {}),
+        // 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 } : {}),
     };
     const renderer = await rendererForType(input.entry.type, rendererRegistry);
     if (renderer?.enrichSearchHit) {
@@ -573,6 +647,7 @@ async function assetToSearchHit(asset, stashDir, sources, config, score, rendere
         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) {
@@ -717,6 +792,21 @@ function deduplicateAssetsByPath(assets) {
         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
+ * before invoking this helper.
+ */
+function entryMatchesScope(scope, filters) {
+    for (const key of ["user", "agent", "run", "channel"]) {
+        const expected = filters[key];
+        if (expected === undefined)
+            continue;
+        if (!scope || scope[key] !== expected)
+            return false;
+    }
+    return true;
+}
 function realpathOrResolve(targetPath) {
     try {
         return fs.realpathSync(targetPath);

package/dist/{indexer → src/indexer}/db.js

@@ -240,7 +240,14 @@ function ensureSchema(db, embeddingDim) {
  */
 function handleVersionUpgrade(db) {
     const storedVersion = getMeta(db, "version");
-    if (!storedVersion || storedVersion === String(DB_VERSION))
+    // BUG-L4: distinguish "missing" (undefined) from "present but empty" — both
+    // were previously coerced through `!storedVersion` and treated as "no
+    // upgrade needed", which caused fresh databases (with no version row) to
+    // skip the upgrade path correctly, but also caused the upgrade path to be
+    // taken when a corrupted/empty version string was persisted. The current
+    // tables get dropped only when the stored version exists AND differs from
+    // DB_VERSION; missing or empty version means a fresh DB and no upgrade.
+    if (storedVersion === undefined || storedVersion === "" || storedVersion === String(DB_VERSION))
         return [];
     let usageBackup = [];
     try {
@@ -258,7 +265,7 @@ function handleVersionUpgrade(db) {
     db.exec("DROP INDEX IF EXISTS idx_entries_type");
     db.exec("DROP TABLE IF EXISTS entries");
     db.exec("DELETE FROM index_meta");
-    console.warn("[akm] Index rebuilt due to version upgrade. Run 'akm index' to repopulate.");
+    warn("[akm] Index rebuilt due to version upgrade. Run 'akm index' to repopulate.");
     return usageBackup;
 }
 /**
@@ -272,22 +279,49 @@ function restoreUsageEventsBackup(db, backup) {
     if (backup.length === 0)
         return;
     try {
+        // BUG-H4: introspect the *target* table's columns rather than relying on
+        // `row[0]`'s keys. The backup may carry columns the new schema dropped,
+        // and the new schema may have NOT-NULL columns without DEFAULT that the
+        // old backup never carried. Project the backup onto the intersection so
+        // we don't silently lose every row to per-row INSERT errors, and warn
+        // once if any backup column was dropped from the new schema.
+        const targetCols = db.prepare("PRAGMA table_info(usage_events)").all().map((c) => c.name);
+        if (targetCols.length === 0) {
+            warn("[db] restoreUsageEventsBackup: usage_events table missing — discarding %d backup row(s)", backup.length);
+            return;
+        }
+        const targetSet = new Set(targetCols);
+        const backupCols = Object.keys(backup[0] ?? {});
+        const projectedCols = backupCols.filter((c) => targetSet.has(c));
+        const droppedCols = backupCols.filter((c) => !targetSet.has(c));
+        if (projectedCols.length === 0) {
+            warn("[db] restoreUsageEventsBackup: no overlapping columns between backup and current schema — discarding %d row(s); dropped: %s", backup.length, droppedCols.join(", ") || "(none)");
+            return;
+        }
+        if (droppedCols.length > 0) {
+            warn("[db] restoreUsageEventsBackup: dropping columns no longer in usage_events schema: %s", droppedCols.join(", "));
+        }
+        let restored = 0;
+        let failed = 0;
         db.transaction(() => {
-            const cols = Object.keys(backup[0]);
-            const placeholders = cols.map(() => "?").join(", ");
-            const insert = db.prepare(`INSERT INTO usage_events (${cols.join(", ")}) VALUES (${placeholders})`);
+            const placeholders = projectedCols.map(() => "?").join(", ");
+            const insert = db.prepare(`INSERT INTO usage_events (${projectedCols.join(", ")}) VALUES (${placeholders})`);
             for (const row of backup) {
                 try {
-                    insert.run(...cols.map((c) => row[c]));
+                    insert.run(...projectedCols.map((c) => row[c]));
+                    restored++;
                 }
                 catch {
-                    /* skip rows that fail */
+                    failed++;
                 }
             }
         })();
+        if (failed > 0) {
+            warn("[db] restoreUsageEventsBackup: restored %d row(s); skipped %d incompatible row(s)", restored, failed);
+        }
     }
-    catch {
-        /* schema changed too much — discard backup gracefully */
+    catch (err) {
+        warn("[db] restoreUsageEventsBackup: discarded %d backup row(s) — %s", backup.length, err instanceof Error ? err.message : String(err));
     }
 }
 // ── Meta helpers ────────────────────────────────────────────────────────────
@@ -488,17 +522,15 @@ export function rebuildFts(db, options) {
         if (skipped > 0) {
             warn(`[db] rebuildFts: skipped ${skipped} entr${skipped === 1 ? "y" : "ies"} with invalid entry_json`);
         }
-        // Always drain the dirty queue — if it exists. A full rebuild also
-        // clears it because the full path covers everything the dirty list
-        // tracks.
-        if (incremental) {
-            db.exec("DELETE FROM entries_fts_dirty");
-        }
-        else {
-            // Full path: drain the dirty queue too. The table is created by
-            // ensureSchema(), so it always exists at this point.
-            db.exec("DELETE FROM entries_fts_dirty");
-        }
+        // Always drain the dirty queue — both paths converge here. The
+        // incremental path drains it because we just consumed every dirty row;
+        // the full path drains it because a full rebuild covers everything the
+        // dirty list tracks. The table is guaranteed to exist (created by
+        // ensureSchema()).
+        //
+        // BUG-L1: previously the if/else arms ran identical statements — the
+        // duplication has been collapsed.
+        db.exec("DELETE FROM entries_fts_dirty");
     })();
 }
 // ── Vector operations ───────────────────────────────────────────────────────
@@ -539,8 +571,26 @@ function float32Buffer(vec) {
     const f32 = new Float32Array(vec);
     return Buffer.from(f32.buffer);
 }
-function bufferToFloat32(buf) {
-    const f32 = new Float32Array(buf.buffer, buf.byteOffset, buf.byteLength / 4);
+/**
+ * Decode a stored embedding BLOB into a Float32 array of `expectedDim`
+ * dimensions. Returns `null` (and emits a warning) when the byte length does
+ * not exactly match `expectedDim * 4`, including the legacy partial-trailing
+ * float case the previous truncating-divide silently swallowed.
+ *
+ * BUG-M2: the previous `buf.byteLength / 4` divide would truncate any
+ * trailing partial float and a misaligned `byteOffset` would throw — both
+ * surfaced as opaque generic errors caught upstream.
+ */
+function bufferToFloat32(buf, expectedDim) {
+    if (buf.byteLength !== expectedDim * 4) {
+        warn("[db] bufferToFloat32: skipping embedding row — expected %d bytes (%d dim x 4), got %d", expectedDim * 4, expectedDim, buf.byteLength);
+        return null;
+    }
+    // Copy into a fresh ArrayBuffer to sidestep any byteOffset alignment
+    // requirements imposed by Float32Array's typed-array view contract.
+    const aligned = new ArrayBuffer(buf.byteLength);
+    new Uint8Array(aligned).set(buf);
+    const f32 = new Float32Array(aligned);
     return Array.from(f32);
 }
 function searchBlobVec(db, queryEmbedding, k) {
@@ -548,9 +598,12 @@ function searchBlobVec(db, queryEmbedding, k) {
         const rows = db.prepare("SELECT id, embedding FROM embeddings").all();
         if (rows.length === 0)
             return [];
+        const expectedDim = queryEmbedding.length;
         const scored = [];
         for (const row of rows) {
-            const embedding = bufferToFloat32(row.embedding);
+            const embedding = bufferToFloat32(row.embedding, expectedDim);
+            if (embedding === null)
+                continue;
             const similarity = cosineSimilarity(queryEmbedding, embedding);
             scored.push({ id: row.id, similarity });
         }

package/dist/{indexer → src/indexer}/file-context.js

@@ -69,9 +69,6 @@ const matchers = [];
 /** Renderer lookup by name. */
 const renderers = new Map();
 let builtinsPromise;
-export function resetBuiltinsCache() {
-    builtinsPromise = undefined;
-}
 /**
  * Ensure that built-in matchers and renderers are registered.
  * Called lazily on first use of runMatchers/getRenderer.

package/dist/src/indexer/graph-boost.js

@@ -0,0 +1,179 @@
+/**
+ * Search-time graph-boost integration for the `akm index` graph pass (#207).
+ *
+ * This module is the consumer half of the graph-extraction pass. It loads
+ * the persisted `graph.json` (when present) and exposes a single helper,
+ * {@link computeGraphBoost}, that the existing FTS5+boosts loop in
+ * `src/indexer/db-search.ts` calls per-entry to obtain an additive boost
+ * value.
+ *
+ * CLAUDE.md / v1 spec compliance:
+ *   - The graph signal feeds the **single** FTS5+boosts pipeline as one
+ *     additive boost component. There is no parallel scoring track.
+ *   - There is no second `SearchHit` scorer. `searchDatabase` continues to
+ *     own ranking; this module just answers "what additive boost does the
+ *     graph contribute for this (query, entry) pair?".
+ *   - Missing/stale/unparseable `graph.json` → boost is `0`. The pipeline
+ *     degrades gracefully to its non-graph behaviour, exactly as today.
+ */
+import fs from "node:fs";
+import { warn } from "../core/warn";
+import { GRAPH_FILE_SCHEMA_VERSION, getGraphFilePath } from "./graph-extraction";
+/**
+ * Per-entry weights, exposed as constants so tests can read them and so the
+ * single-source-of-truth for "how much does the graph contribute" is here
+ * rather than inlined into `db-search.ts`. Kept conservative — the goal is
+ * a useful tiebreaker, not domination of the lexical signal.
+ */
+export const GRAPH_DIRECT_BOOST_PER_ENTITY = 0.25;
+export const GRAPH_DIRECT_BOOST_CAP = 0.75;
+export const GRAPH_HOP_BOOST_PER_ENTITY = 0.1;
+export const GRAPH_HOP_BOOST_CAP = 0.3;
+/**
+ * Load the graph file for a stash root and pre-compute everything that's
+ * shared across all entries scored for one query. Returns `null` when:
+ *   - `graph.json` does not exist.
+ *   - The file fails to parse.
+ *   - The schema version doesn't match (treated like "missing" so an old
+ *     index keeps working until the next `akm index --full`).
+ *   - The query produces no token-level entity matches (no boost is
+ *     possible, so we skip the per-entry overhead entirely).
+ */
+export function loadGraphBoostContext(stashRoot, query) {
+    const graph = readGraphFile(stashRoot);
+    if (!graph)
+        return null;
+    const queryTokens = query
+        .toLowerCase()
+        .split(/[\s\-_/]+/)
+        .filter((t) => t.length >= 2);
+    if (queryTokens.length === 0)
+        return null;
+    // Build a flat union of all extracted entities across the corpus. This
+    // is small (capped per-asset at extract time) and lets the per-entry
+    // path do a single set membership test.
+    const allEntities = new Set();
+    const nodesByPath = new Map();
+    for (const node of graph.files) {
+        nodesByPath.set(node.path, node);
+        for (const entity of node.entities)
+            allEntities.add(entity);
+    }
+    // An entity matches the query when any of its sub-tokens equals or
+    // contains a query token. Cheap and forgiving — exact substring match is
+    // sufficient because both sides are already lower-cased at extract time.
+    const matchedEntities = new Set();
+    for (const entity of allEntities) {
+        const entityTokens = entity.split(/[\s\-_/]+/).filter(Boolean);
+        for (const qt of queryTokens) {
+            if (entity === qt || entity.includes(qt) || entityTokens.some((et) => et === qt)) {
+                matchedEntities.add(entity);
+                break;
+            }
+        }
+    }
+    if (matchedEntities.size === 0)
+        return null;
+    // One-hop neighbours: any entity that appears on the other end of a
+    // relation whose other endpoint is in matchedEntities.
+    const oneHopEntities = new Set();
+    for (const node of graph.files) {
+        for (const rel of node.relations) {
+            if (matchedEntities.has(rel.from) && !matchedEntities.has(rel.to)) {
+                oneHopEntities.add(rel.to);
+            }
+            else if (matchedEntities.has(rel.to) && !matchedEntities.has(rel.from)) {
+                oneHopEntities.add(rel.from);
+            }
+        }
+    }
+    return { nodesByPath, matchedEntities, oneHopEntities };
+}
+/**
+ * Compute the graph-boost contribution for a single scored entry.
+ *
+ * The return value is added directly into `boostSum` in `searchDatabase`'s
+ * existing scoring loop — same units, same cap policy. Returns `0` when
+ * the entry's file isn't in the graph or when no entity overlap exists.
+ */
+export function computeGraphBoost(context, filePath) {
+    const node = context.nodesByPath.get(filePath);
+    if (!node)
+        return 0;
+    let directHits = 0;
+    let hopHits = 0;
+    for (const entity of node.entities) {
+        if (context.matchedEntities.has(entity))
+            directHits += 1;
+        else if (context.oneHopEntities.has(entity))
+            hopHits += 1;
+    }
+    const directBoost = Math.min(GRAPH_DIRECT_BOOST_CAP, directHits * GRAPH_DIRECT_BOOST_PER_ENTITY);
+    const hopBoost = Math.min(GRAPH_HOP_BOOST_CAP, hopHits * GRAPH_HOP_BOOST_PER_ENTITY);
+    return directBoost + hopBoost;
+}
+/**
+ * Lightweight reader — extracted so the boost loader and tests share one
+ * code path. Tolerant of missing files (returns null) but logs a warning
+ * when an existing file fails to parse so corruption is visible.
+ */
+function readGraphFile(stashRoot) {
+    const target = getGraphFilePath(stashRoot);
+    let raw;
+    try {
+        raw = fs.readFileSync(target, "utf8");
+    }
+    catch {
+        // Missing → no boost. Not an error: the user simply hasn't enabled
+        // graph extraction yet, or the pass hasn't run.
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        warn(`graph boost: failed to parse ${target}: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+    if (!isGraphFile(parsed) || parsed.schemaVersion !== GRAPH_FILE_SCHEMA_VERSION) {
+        return null;
+    }
+    return parsed;
+}
+function isGraphFile(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const obj = value;
+    if (typeof obj.schemaVersion !== "number")
+        return false;
+    if (typeof obj.generatedAt !== "string")
+        return false;
+    if (typeof obj.stashRoot !== "string")
+        return false;
+    if (!Array.isArray(obj.files))
+        return false;
+    for (const f of obj.files) {
+        if (typeof f !== "object" || f === null)
+            return false;
+        const node = f;
+        if (typeof node.path !== "string")
+            return false;
+        if (typeof node.type !== "string")
+            return false;
+        if (!Array.isArray(node.entities) || !node.entities.every((e) => typeof e === "string"))
+            return false;
+        if (!Array.isArray(node.relations))
+            return false;
+        for (const r of node.relations) {
+            if (typeof r !== "object" || r === null)
+                return false;
+            const rel = r;
+            if (typeof rel.from !== "string" || typeof rel.to !== "string")
+                return false;
+            if (rel.type !== undefined && typeof rel.type !== "string")
+                return false;
+        }
+    }
+    return true;
+}