homegraph 1.5.6 → 1.5.8

package/CHANGELOG.md

@@ -10,6 +10,57 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## [Unreleased]
 
 
+## [1.5.8] - 2026-09-15
+
+### Improvements
+
+- SQLite no longer depends on optional `better-sqlite3`. Backends are **`node:sqlite`** (Node ≥22.5 with FTS5) then **`node-sqlite3-wasm`**. Install trees drop ~10 MiB of unused native-addon source when vendor/offline packaging skips `prebuild-install`. `HOMEGRAPH_SQLITE_BACKEND=native` is ignored (use `node-sqlite` or `wasm`). Prefer Node 22.5+ for WAL (Spec 0033).
+- Published `dist/` no longer includes source maps; vendored tree-sitter grammars are copied from an explicit list (unlisted files such as leftover wasm are not shipped). The `openai` package is an optional dependency used only by spec LLM commands — install it when running `homegraph spec` against an API (`npm install openai`). MCP `serve mcp` does not require it (Spec 0031).
+- MCP product hosts get a unified **four-state** index readiness in tool results (`empty` / `fast` / `full` / `syncing`): deep tools and `homegraph_project` return success-shaped guidance with `status=…` instead of ambiguous phase prose; `tools/list` stays fully exposed. Auto-init cold start sets `building_fast` immediately after creating the empty DB, serializes empty-DB creation with `homegraph.lock`, and opens an existing index when a concurrent init wins. **Fast build** runs in-process; **full build** continues in the same MCP/daemon process in the background (`indexAll` yields between batches — no sibling `homegraph index` CLI, so there is no second writer to lock against). SQLite busy / write-lock contention maps to `syncing` rather than `isError`. The file watcher starts after the full build finishes (Spec 0032).
+- ArkTS exploration now finds bounded directed paths between named anchors, selecting intermediate declarations and registration sources together. Typed state/event goals, exact qualified-name recovery, ambiguity gaps and explicit stop reasons reduce missing connections without treating shared callees as a path. `HOMEGRAPH_ARKTS_QUERY_PATHS=0` restores the first-batch evidence strategy for comparison; indexing and external tool interfaces are unchanged (Spec 0030).
+- ArkTS symbol/flow exploration now selects complete source declarations and the dependencies of static relation evidence together. Explicit gaps identify omitted, stale and unindexed evidence; output and planner budgets no longer cut these packs mid-body. Virtual ArkAnalyzer entries are excluded, cache hits validate source fingerprints, and `HOMEGRAPH_ARKTS_EVIDENCE_PACKS=0` restores legacy rendering for comparison (Spec 0029). Literal/resource and focused usages/modules/native routes retain their existing behavior.
+
+### Fixes
+
+- An MCP host's explicit project declaration (`--path`, or the client's `rootUri`/`workspaceFolders`) is now a **floor** for root resolution: a stray ancestor `.homegraph/` above it is never adopted. Previously a nested server walked up unbounded and could latch onto an unrelated ancestor index — observed live as a DevEco evaluation session creating `.homegraph` at a benchmark harness root, after which every nested project's daemon tried to index the entire result tree (OOM at 3.5GB in 48s) while its server was SIGKILL'd by the 60s liveness watchdog with every tool call hanging as `Connection closed`. Bare `serve mcp` and CLI commands keep the git-style unbounded walk-up; tool-level `projectPath` resolution is unchanged (Spec 0028).
+- `homegraph_explore`'s description no longer reports `Budget: make at most 1 calls for this project (0 files indexed)` while auto-init is still building. Hosts snapshot `tools/list` once at connect, so that transient "0 files" read as terminal and agents abandoned HomeGraph for the whole session even though the index completed seconds later. The 0-file description now matches what a call actually returns: a failed build asks the agent to relay `homegraph index` to the user, an in-flight build points at `homegraph_project` and says to retry once indexing finishes, and a genuinely empty project says so honestly. Indexed repos keep the usual call-budget note unchanged (Spec 0027).
+
+## [1.5.7] - 2026-09-09
+
+### Fixes
+
+- ArkTS indexing aligns with ArkAnalyzer `ClassCategory`: **object literals**, **type literals**, and **unions** are no longer stored as HomeGraph `class` nodes (they were inflating `graph_class` as `<Object$anon@N>` / `%AC*` under the file). Real classes — including true anonymous `ClassCategory.CLASS` — are unchanged. Re-index to refresh existing databases (Spec 0026).
+- Harmony multi-module ArkTS indexing: register **synthetic PROJECT modules** for ArkAnalyzer sources that sit outside `build-profile.json5` `srcPath` (e.g. ohrouter `HMRouterPlugin/**/*.ts`), so they enter the same `analyseByModule` pipeline instead of being skipped by both AA and tree-sitter. Incremental dirty mapping can target those synthetic roots. AA-persisted files now get truthful `files`/`nodes.language` by extension (`.ets`→`arkts`, `.ts`/`.d.ts`→`typescript`) instead of hard-coding `arkts` (Spec 0025).
+
+### Improvements
+
+- Prefer ordinary bash/search/read for source localization and use graph tools only for an unresolved relation. Remove mandatory explore-first guidance in both MCP initialization and tool descriptions; retain indexing, query schemas and validation requirements (Spec 0028).
+- Preserve the action and constraints in explore queries, use repository-relative paths, and optionally label node source excerpts with a content identity for trace analysis (`HOMEGRAPH_SOURCE_RECEIPTS=1`, Spec 0027).
+
+- MCP `initialize` instructions: **single-file path-pinned edits → Read + edit, skip `homegraph_*`**; explore only when locate/cross-file is needed.
+- Explore **defers** (`Skip HomeGraph`, kind `path-pinned-edit`) when the query names one `…/File.ext` and is a code-change shape — avoids explore context tax on 082-style tasks.
+- Path scaffolding (`features/.../Foo.ets` + basename-as-Type) no longer counts as multi-anchor; `.ets`/`.ts`/… are not parsed as member access.
+
+### New Features
+
+- Standard-library Python retrieval debugger with an original-source Spatial Upscale demo, interactive steps, rules/LLM comparison, and persistent MCP/Planner evidence and error records (Spec 0025).
+
+- Experimental structured query planning for explore (Spec 0022): shared local routing features; optional, explicitly configured one-call model intent/decomposition/rephrase; bounded dependent retrieval with a shared deadline/output budget, validated anchors, worker propagation, context hints and direction-aware cache keys. Model failures fall back locally; compact diagnostic metadata includes planning usage/time and per-step coverage. No remote model calls by default.
+
+### Fixes
+
+- Grounded retrieval plans separate concise semantic concepts, verbatim UI text, exact anchors, source scope and relationship direction. Unanchored reference requests first discover source and retain the missing reference obligation. Bounded literal/resource lookup prioritizes local application evidence; rendering deduplicates same-source declarations and marks incomplete evidence. Repeat protection permits a bounded recovery for weak or changed evidence, and retrieval guidance no longer closes the coding task (Spec 0024).
+- The optional model planner now requests English step queries and short English semantic search terms, while preserving literal identifiers, paths and task constraints. This is a prompt-only refinement: retrieval, anchor validation, request count and budgets are unchanged (Spec 0023).
+- Model-planned explore steps now keep their own retrieval terms instead of repeating the whole task as search seeds. General/flow steps consume planned hints through full context retrieval; task constraints remain separate. Dependency candidates come only from displayed source declarations and retain node/file identity, with visible location receipts surviving shared-output trimming. Unseen fuzzy hits and inherited nodes no longer manufacture new bindings; default rule routes are unchanged (Spec 0023).
+- Explicit model planning now considers task-scoped natural-language queries before shape fast paths; exact symbol/path lookups remain cheap. Compact metadata explains planning eligibility, skip reasons and the original rule route, separately from provider failures (Spec 0023).
+- Planner instructions distinguish read-only evidence lookup from code-editing workflows and provide a compact JSON shape; more than three steps still fail closed, with a specific step-count diagnostic and no silent truncation or retry (Spec 0023).
+- After a model planning request fails, local fallback retrieval now uses the remaining shared deadline instead of the unbounded main-thread fast path; rule-only fast retrieval is unchanged (Spec 0023).
+- Query planning keeps framework labels out of lexical retrieval, preserves host-provided task constraints before agent shorthand, accepts bounded numeric step IDs, and supports an explicit planning timeout up to 10 seconds while reserving retrieval time within the shared deadline (default remains 5 seconds; Spec 0023).
+- Experimental query planning (Spec 0023): focused feature queries cannot be broadened into whole-project overviews by a model rewrite. Optional bounded task context preserves original actions/product scope across planning and cache keys; model-proposed broad anchors are discarded when an unauthorized overview is downgraded. Explicit project maps remain supported.
+- An explicit `HOMEGRAPH_MCP_TOOLS` selection now overrides default small-repository tool trimming, so requested specialized tools remain callable on small ArkTS projects (Spec 0023).
+
+- MCP first-tool guidance now gives `homegraph_usages`, `homegraph_modules`, and `homegraph_native` mutually exclusive priority for their narrow intents instead of simultaneously telling agents those questions are explore-first; general `homegraph_explore` remains the compatibility fallback and still auto-routes high-confidence shapes.
+
 ## [1.5.6] - 2026-09-03
 
 ### New Features
@@ -187,3 +238,5 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 [1.5.0]: https://gitcode.com/ProgramAnalysis/homegraph/tags/v1.5.0
 [1.4.1]: https://gitcode.com/ProgramAnalysis/homegraph/tags/v1.4.1
 [1.5.6]: https://github.com/fujiaxin-coder/homegraph/releases/tag/v1.5.6
+[1.5.7]: https://github.com/fujiaxin-coder/homegraph/releases/tag/v1.5.7
+[1.5.8]: https://github.com/fujiaxin-coder/homegraph/releases/tag/v1.5.8

package/README.md

@@ -15,7 +15,7 @@
 
 ### 1. 安装 CLI
 
-需要 **Node.js 22+**（推荐 22.5+ 或 24）。SQLite 优先用内置 `node:sqlite`（≥22.5），否则 `better-sqlite3`（12.x），再不行回退 `node-sqlite3-wasm`。
+需要 **Node.js 22+**（推荐 22.5+ 或 24）。SQLite 优先用内置 `node:sqlite`（≥22.5 且含 FTS5），否则回退 `node-sqlite3-wasm`。
 
 ```bash
 npm install -g homegraph
@@ -179,10 +179,10 @@ Agent 侧工具名前缀为 `homegraph_`。
 
 | 工具 | 用途 |
 |------|------|
-| `homegraph_explore` | **主工具**：一次调用返回相关符号的完整源码、调用路径与影响范围；支持自然语言问题或符号/文件名列表。高置信度的用法 / 模块依赖 / NAPI 问法会委派到下方三个聚焦工具的同一套 survey |
-| `homegraph_usages` | 只读用法清单：命名 API / member / field / 常量的引用与调用点（常量袋可走有界文本扫描） |
-| `homegraph_modules` | 只读模块依赖 / 循环依赖清单（命名模块或路径） |
-| `homegraph_native` | 只读 NAPI / native export 清单（命名路径或 Type） |
+| `homegraph_usages` | **精确用法清单首选**：查询一个已命名 API、成员、常量或字段在哪里被引用 |
+| `homegraph_modules` | **模块拓扑首选**：查询已命名模块之间的依赖关系或循环依赖 |
+| `homegraph_native` | **Native 边界首选**：查询已命名路径或类型的 NAPI/native 导出和注册位置 |
+| `homegraph_explore` | **通用结构探索**：一次调用返回相关符号的源码、调用路径与影响范围；窄清单问题优先使用上面三个专用工具 |
 | `homegraph_search` | 按名称快速搜索符号（仅返回位置，不含源码） |
 | `homegraph_node` | 读取单个符号或整个文件的源码（带行号）及调用关系；可替代 Read 读文件 |
 | `homegraph_callers` / `homegraph_callees` | 查看调用方 / 被调用方 |
@@ -195,6 +195,12 @@ Agent 侧工具名前缀为 `homegraph_`。
 | `homegraph_spec_find` | 根据文件路径反向查找关联的Spec |
 | `homegraph_spec_trace` | 根据代码符号追溯回关联的Spec |
 
+### 查询规划（实验性）
+
+`homegraph_explore` 现在共用结构化查询计划：默认 `HOMEGRAPH_QUERY_PLANNER=rules`，保持本地确定性路由；`off` 可回退旧执行路径。显式启用 `llm` 后，复杂问题可在一次模型调用中做意图识别、问题分解和检索改写，再复用既有工具的内部实现。
+
+模型规划需要单独配置 URL、模型和密钥；仅发送问题，不发送仓库源码。最多 3 个子任务共用截止时间和输出预算，规划失败退回本地规则。配置、指标、限制见 [查询规划指南](docs/query-planning.md)。这不是新增的 CodeGraph 构建算法，也尚未证明能降低真实任务的 token 或延迟。
+
 ### Commit4Spec（Spec知识图谱）
 
 Commit4Spec 提供两条互补路径将设计Spec与 Git 历史关联，存入 `.homegraph/commit4spec/commit4spec.db`：
@@ -350,7 +356,7 @@ Cursor 等项目级配置写入 `./.cursor/mcp.json`，格式相同。推荐使
 
 ## 环境要求
 
-- Node.js **22+**（推荐 22.5+ 或 24；SQLite：`node:sqlite` → better-sqlite3 12.x → wasm）
+- Node.js **22+**（推荐 22.5+ 或 24；SQLite：`node:sqlite` → wasm）
 - 首次索引时会对项目源码做 AST 解析，大型仓库首次 `init -i` 可能需要数分钟
 - WSL2 下若项目位于 Windows 盘符（`/mnt/c` 等）且 MCP 连接不稳定，可设置 `HOMEGRAPH_NO_DAEMON=1` 跳过共享后台服务，每个会话独立运行
 

package/dist/bin/homegraph.js

@@ -573,6 +573,7 @@ function main() {
         .option('-f, --force', 'Index even if the path looks like your home directory or a filesystem root')
         .option('-q, --quiet', 'Suppress progress output')
         .option('-v, --verbose', 'Show detailed worker lifecycle and memory info')
+        .option('--inplace', 'Index into the existing database without recreating it (MCP auto-init; DB may already be open by the parent)')
         .action(async (pathArg, options) => {
         const projectPath = resolveProjectPath(pathArg);
         try {
@@ -589,16 +590,13 @@ function main() {
                 process.exit(1);
             }
             const { default: HomeGraph } = await loadHomeGraph();
-            // `index` is a FULL re-index — identical to a fresh `init`. RECREATE the
-            // database from scratch (discard .homegraph/homegraph.db + its WAL) rather
-            // than opening the old graph and DELETE-ing every row. The clear-then-index
-            // approach reported "0 nodes" without the clear (#874); the recreate keeps
-            // that fixed AND avoids the failure mode where, on a large or pre-fix
-            // poisoned index, the per-row FTS delete churn wedged the main thread long
-            // enough to trip the liveness watchdog before scanning even began (#1067).
-            // recreate() hands back a fresh, empty instance — no clear() needed. For
-            // fast incremental updates use `sync`.
-            const cg = await HomeGraph.recreate(projectPath);
+            // Default `index` is a FULL re-index via recreate(). MCP auto-init already
+            // created an empty DB and keeps it open in the parent — recreate() cannot
+            // unlink the file on Windows (EPERM) and the detached child exits with 0
+            // files (Spec 0032). `--inplace` opens the existing DB and indexAll()s.
+            const cg = options.inplace
+                ? await HomeGraph.open(projectPath, { sources: 'both' })
+                : await HomeGraph.recreate(projectPath);
             // Supervise the indexer: self-terminate if orphaned (parent shim killed)
             // or if the main thread wedges — neither was guarded on this path (#999).
             const supervision = (0, command_supervision_1.installCommandSupervision)('index');
@@ -809,10 +807,9 @@ function main() {
                     warn('The write-ahead log is larger than the database — killed sessions left it behind. It is reclaimed automatically on open; if it persists across runs, another live HomeGraph process is holding it.');
                 }
             }
-            // Prefer node:sqlite → better-sqlite3; wasm is last-resort (no WAL).
+            // Prefer node:sqlite; wasm is last-resort (no WAL).
             const backendLabel = backend === 'node-sqlite' ? chalk.green('node-sqlite')
-                : backend === 'native' ? chalk.green('native (better-sqlite3)')
-                    : chalk.yellow(`wasm ${(0, glyphs_1.getGlyphs)().dash} slower fallback; use Node 22.5+ or \`npm rebuild better-sqlite3\``);
+                : chalk.yellow(`wasm ${(0, glyphs_1.getGlyphs)().dash} slower fallback; use Node 22.5+ for built-in node:sqlite`);
             console.log(`  Backend:   ${backendLabel}`);
             const journalLabel = journalMode === 'wal'
                 ? chalk.green('wal')
@@ -1415,7 +1412,12 @@ function main() {
      * explains this to anyone who runs it by hand.
      */
     async function runServeMcp(options) {
-        const projectPath = options.path ? resolveProjectPath(options.path) : undefined;
+        // An MCP host's --path is a DECLARATION of the project root, not a search
+        // hint: resolve it literally and never walk up past it (spec 0028). A stray
+        // ancestor .homegraph above the declared root otherwise hijacks the session
+        // (observed as a harness-root index poisoning every nested bench project).
+        // resolveProjectPath keeps its subdir walk-up for the human CLI subcommands.
+        const projectPath = options.path ? path.resolve(options.path) : undefined;
         // Commander sets watch=false when --no-watch is passed. Route it through
         // the same env-var chokepoint the watcher and MCP server already honor.
         if (options.watch === false) {

package/dist/context/index.js

@@ -48,6 +48,7 @@ const errors_1 = require("../errors");
 const utils_1 = require("../utils");
 const query_utils_1 = require("../search/query-utils");
 const markers_1 = require("./markers");
+const literal_evidence_1 = require("../search/literal-evidence");
 /**
  * Extract likely symbol names from a natural language query
  *
@@ -204,6 +205,33 @@ const DEFAULT_FIND_OPTIONS = {
     edgeKinds: [],
     nodeKinds: HIGH_VALUE_NODE_KINDS, // Filter out imports/exports by default
 };
+/** Hints may cross a worker/library boundary; never trust their runtime shape. */
+function normalizeRetrievalHints(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const hints = value;
+    if (!Array.isArray(hints.symbols) || !Array.isArray(hints.searchTerms))
+        return undefined;
+    const normalize = (items, lowerCase) => {
+        const result = new Set();
+        for (const item of items.slice(0, 32)) {
+            if (typeof item !== 'string' || item.length > 256 || /[\u0000-\u001f\u007f]/.test(item))
+                continue;
+            const term = item.trim();
+            if (term)
+                result.add(lowerCase ? term.toLowerCase() : term);
+        }
+        return [...result];
+    };
+    return {
+        symbols: normalize(hints.symbols, false),
+        searchTerms: normalize(hints.searchTerms, true),
+        ...(Array.isArray(hints.nodeIds) ? { nodeIds: normalize(hints.nodeIds, false) } : {}),
+        ...(Array.isArray(hints.literalTexts) ? { literalTexts: (0, literal_evidence_1.normalizeLiteralTexts)(hints.literalTexts) } : {}),
+        ...(['local', 'sdk', 'all'].includes(String(hints.sourceScope))
+            ? { sourceScope: hints.sourceScope } : {}),
+    };
+}
 // Re-export the low-confidence sentinel (defined in a dependency-free leaf so
 // the MCP layer can import it without pulling this module's deps onto the
 // cold-start path). Builder code below uses the imported binding directly.
@@ -455,18 +483,58 @@ class ContextBuilder {
      */
     async findRelevantContext(query, options = {}) {
         const opts = { ...DEFAULT_FIND_OPTIONS, ...options };
+        const hints = normalizeRetrievalHints(opts.retrievalHints);
         // Start with empty subgraph
         const nodes = new Map();
         const edges = [];
         const roots = [];
-        // Handle empty query - return empty subgraph
-        if (!query || query.trim().length === 0) {
+        // Identity-only retrieval does not need to invent a lexical query.
+        if ((!query || query.trim().length === 0) && !hints?.nodeIds?.length && !hints?.literalTexts?.length) {
             return { nodes, edges, roots };
         }
         // === HYBRID SEARCH ===
-        // Step 1: Extract potential symbol names from query
-        const symbolsFromQuery = extractSymbolsFromQuery(query);
-        (0, errors_1.logDebug)('Extracted symbols from query', { query, symbols: symbolsFromQuery });
+        // Step 1: Reuse the shared plan when supplied. An intentionally empty hint
+        // list remains empty: re-extracting from the question would undo planning.
+        const symbolsFromQuery = hints?.symbols ?? extractSymbolsFromQuery(query);
+        const searchTerms = hints?.searchTerms ?? (0, query_utils_1.extractSearchTerms)(query);
+        (0, errors_1.logDebug)('Context retrieval symbols', { query, symbols: symbolsFromQuery, planned: !!hints });
+        // A binding is an identity, not a name search hint. Revalidate it in this
+        // index and keep it outside fuzzy scoring/import redirection: converting a
+        // bound ID back to a bare name can silently switch to another file's node.
+        // Explicit kind filters still apply; the default lexical kind filter must
+        // not discard an explicitly bound file/import/property node.
+        const boundResults = [];
+        for (const id of hints?.nodeIds ?? []) {
+            const node = this.queries.getNodeById(id);
+            if (!node || (options.nodeKinds?.length && !options.nodeKinds.includes(node.kind)))
+                continue;
+            boundResults.push({ node, score: 0 });
+        }
+        const boundIds = new Set(boundResults.map(result => result.node.id));
+        // Verbatim labels are an independent retrieval channel. The witness range
+        // stays available even when the UI/resource file has no extracted AST node.
+        const literalEvidence = hints?.literalTexts?.length && hints.sourceScope !== 'sdk'
+            ? (0, literal_evidence_1.findLiteralEvidence)(this.projectRoot, {
+                literalTexts: hints.literalTexts,
+                files: this.queries.getAllFiles().map(file => file.path),
+            }) : undefined;
+        const literalResults = [];
+        const literalIds = new Set();
+        for (const hit of literalEvidence?.hits ?? []) {
+            const candidates = this.queries.getNodesByFile(hit.filePath)
+                .filter(node => node.startLine <= hit.line && node.endLine >= hit.line
+                && !['import', 'export', 'parameter'].includes(node.kind)
+                && (!options.nodeKinds?.length || options.nodeKinds.includes(node.kind)))
+                .sort((a, b) => {
+                const callable = (node) => ['method', 'function', 'component'].includes(node.kind) ? 1 : 0;
+                return callable(b) - callable(a) || (a.endLine - a.startLine) - (b.endLine - b.startLine);
+            });
+            const node = candidates[0];
+            if (node && !literalIds.has(node.id)) {
+                literalIds.add(node.id);
+                literalResults.push({ node, score: 1000 });
+            }
+        }
         // Step 2: Look up exact matches for extracted symbols
         let exactMatches = [];
         if (symbolsFromQuery.length > 0) {
@@ -618,7 +686,6 @@ class ContextBuilder {
         // where file names are the primary identifiers.
         let textResults = [];
         try {
-            const searchTerms = (0, query_utils_1.extractSearchTerms)(query);
             if (searchTerms.length > 0) {
                 // Search each term individually to get broader coverage,
                 // then boost results that match multiple terms
@@ -736,7 +803,7 @@ class ContextBuilder {
         // than nodes matching just one generic term. Without this, "ExecutionUtils"
         // (matches only "execution") fills budget slots meant for "ShardSearchRequest"
         // (matches "shard" + "search" + "request").
-        const queryTermsForBoost = (0, query_utils_1.extractSearchTerms)(query);
+        const queryTermsForBoost = searchTerms;
         if (queryTermsForBoost.length >= 2) {
             // Group terms that are substrings of each other (stem variants of the same
             // root word). "indexed", "indexe", "index" should count as ONE concept match,
@@ -976,6 +1043,13 @@ class ContextBuilder {
         // Final sort and truncation — all search channels (exact, text, CamelCase,
         // compound) have now contributed. Sort by score so multi-term matches from
         // later steps can outrank dampened single-term matches from earlier steps.
+        // Planner scope is explicit, not a growing vocabulary of prose stopwords.
+        // SDK-only lexical matches cannot establish a local business entry point.
+        const isSdkResult = (result) => result.node.filePath.startsWith('ohos-sdk:');
+        if (hints?.sourceScope === 'local')
+            searchResults = searchResults.filter(result => !isSdkResult(result));
+        else if (hints?.sourceScope === 'sdk')
+            searchResults = searchResults.filter(isSdkResult);
         searchResults.sort((a, b) => b.score - a.score);
         searchResults = searchResults.slice(0, opts.searchLimit * 3);
         // Filter by minimum score
@@ -984,6 +1058,22 @@ class ContextBuilder {
         // If someone searches "terminal" and finds `import { TerminalPanel }`,
         // they want the TerminalPanel class, not the import statement
         filteredResults = this.resolveImportsToDefinitions(filteredResults);
+        if (hints?.sourceScope === 'local')
+            filteredResults = filteredResults.filter(result => !isSdkResult(result));
+        if (hints?.sourceScope === 'sdk')
+            filteredResults = filteredResults.filter(isSdkResult);
+        if (literalResults.length) {
+            // Reserve first roots for observed UI text before native graph-density
+            // heuristics. Bound identities, if supplied below, still take priority.
+            filteredResults = [...literalResults, ...filteredResults.filter(result => !literalIds.has(result.node.id))];
+        }
+        if (boundResults.length > 0) {
+            const rootLimit = Math.max(0, Math.min(Number.isFinite(opts.searchLimit) ? Math.floor(opts.searchLimit) : DEFAULT_FIND_OPTIONS.searchLimit, Number.isFinite(opts.maxNodes) ? Math.floor(opts.maxNodes) : DEFAULT_FIND_OPTIONS.maxNodes));
+            filteredResults = [
+                ...boundResults,
+                ...filteredResults.filter(result => !boundIds.has(result.node.id)),
+            ].slice(0, rootLimit);
+        }
         // Cap entry points so traversal budget isn't spread too thin.
         // With 36 entry points and maxNodes=120, each gets only 3 nodes — useless.
         // Cap to searchLimit so each entry point gets a meaningful traversal budget.
@@ -999,7 +1089,8 @@ class ContextBuilder {
         // Single-keyword and symbol-name queries are exempt (their single match IS the
         // answer), so the handoff never fires on them.
         let confidence = 'high';
-        const confTerms = (0, query_utils_1.extractSearchTerms)(query, { stems: false }).filter(t => t.length >= 3);
+        const confTerms = (hints?.searchTerms ?? (0, query_utils_1.extractSearchTerms)(query, { stems: false }))
+            .filter(t => t.length >= 3);
         if (confTerms.length >= 2 && filteredResults.length > 0) {
             const distinctive = new Set(symbolsFromQuery.filter(query_utils_1.isDistinctiveIdentifier).map(s => s.toLowerCase()));
             const anyStrong = filteredResults.some(r => {
@@ -1016,7 +1107,7 @@ class ContextBuilder {
                 }
                 return false;
             });
-            if (!anyStrong)
+            if (!anyStrong && !literalResults.length)
                 confidence = 'low';
         }
         // Add entry points to subgraph
@@ -1030,7 +1121,10 @@ class ContextBuilder {
         // ensures subclasses and superclasses always appear in results.
         // Budget: up to maxNodes/4 hierarchy nodes to avoid flooding.
         const typeHierarchyKinds = new Set(['class', 'interface', 'struct', 'trait', 'protocol']);
-        const maxHierarchyNodes = Math.ceil(opts.maxNodes / 4);
+        // Identity-bound retrieval uses the bounded BFS below for hierarchy edges
+        // as well. The legacy full hierarchy survey ignores traversalDepth and can
+        // visit an entire family even for a depth-zero binding lookup.
+        const maxHierarchyNodes = boundResults.length > 0 ? 0 : Math.ceil(opts.maxNodes / 4);
         let hierarchyNodesAdded = 0;
         for (const result of filteredResults) {
             if (hierarchyNodesAdded >= maxHierarchyNodes)
@@ -1153,14 +1247,19 @@ class ContextBuilder {
                 method: 1, function: 1, property: 0, field: 0, variable: 0,
             };
             nodeIds.sort((a, b) => {
+                const bindingOrder = Number(boundIds.has(b)) - Number(boundIds.has(a));
+                if (bindingOrder)
+                    return bindingOrder;
                 const aRoot = rootSet.has(a) ? 10 : 0;
                 const bRoot = rootSet.has(b) ? 10 : 0;
                 const aKind = kindPriority[finalNodes.get(a).kind] ?? 0;
                 const bKind = kindPriority[finalNodes.get(b).kind] ?? 0;
                 return (bRoot + bKind) - (aRoot + aKind);
             });
-            // Remove excess nodes (keep the highest-priority ones)
-            for (const id of nodeIds.slice(maxPerFile)) {
+            // Explicit identities already paid for a bounded root slot. Diversity
+            // preferences must not erase them; total maxNodes still remains a cap.
+            const keepPerFile = Math.max(maxPerFile, nodeIds.filter(id => boundIds.has(id)).length);
+            for (const id of nodeIds.slice(keepPerFile)) {
                 finalNodes.delete(id);
             }
         }
@@ -1168,12 +1267,13 @@ class ContextBuilder {
         // at most 15% of the budget. Many codebases have dozens of near-identical
         // test implementations (e.g., 6 Guard classes in integration tests) that
         // individually survive score dampening but collectively flood the result.
-        // Test entry points are NOT exempt — they should be evicted too.
+        // Lexically chosen test entry points are NOT exempt. Explicit identity
+        // bindings are exempt from this preference, but not from maxNodes.
         if (!isTestQuery) {
             const maxNonProd = Math.max(3, Math.ceil(opts.maxNodes * 0.15));
             const nonProdIds = [];
             for (const [id, node] of finalNodes) {
-                if ((0, query_utils_1.isTestFile)(node.filePath)) {
+                if ((0, query_utils_1.isTestFile)(node.filePath) && !boundIds.has(id)) {
                     nonProdIds.push(id);
                 }
             }
@@ -1201,7 +1301,12 @@ class ContextBuilder {
                 existingEdgeKeys.add(key);
             }
         }
-        return { nodes: finalNodes, edges: finalEdges, roots, confidence };
+        return {
+            nodes: finalNodes, edges: finalEdges,
+            roots: boundResults.length > 0 ? roots.filter(id => finalNodes.has(id)) : roots,
+            confidence,
+            ...(literalEvidence ? { literalEvidence } : {}),
+        };
     }
     /**
      * Get the source code for a node

package/dist/db/index.d.ts

@@ -5,7 +5,7 @@
  */
 import { SqliteDatabase, SqliteBackend } from './sqlite-adapter';
 import { SchemaVersion } from '../types';
-export { SqliteDatabase, SqliteBackend, WASM_FALLBACK_FIX_RECIPE, isNodeSqliteAvailable, isNodeSqliteFts5Available, isNativeSqliteAvailable, } from './sqlite-adapter';
+export { SqliteDatabase, SqliteBackend, WASM_FALLBACK_FIX_RECIPE, isNodeSqliteAvailable, isNodeSqliteFts5Available, } from './sqlite-adapter';
 /**
  * WAL size past which `healOversizedWal` (run at every `open`) checkpoints and
  * truncates the file, and to which `journal_size_limit` clips the WAL after any

package/dist/db/index.js

@@ -38,7 +38,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DATABASE_FILENAME = exports.DatabaseConnection = exports.WAL_HEAL_THRESHOLD_BYTES = exports.isNativeSqliteAvailable = exports.isNodeSqliteFts5Available = exports.isNodeSqliteAvailable = exports.WASM_FALLBACK_FIX_RECIPE = void 0;
+exports.DATABASE_FILENAME = exports.DatabaseConnection = exports.WAL_HEAL_THRESHOLD_BYTES = exports.isNodeSqliteFts5Available = exports.isNodeSqliteAvailable = exports.WASM_FALLBACK_FIX_RECIPE = void 0;
 exports.resolveWalHealBytes = resolveWalHealBytes;
 exports.getDatabasePath = getDatabasePath;
 exports.removeDatabaseFiles = removeDatabaseFiles;
@@ -51,7 +51,6 @@ var sqlite_adapter_2 = require("./sqlite-adapter");
 Object.defineProperty(exports, "WASM_FALLBACK_FIX_RECIPE", { enumerable: true, get: function () { return sqlite_adapter_2.WASM_FALLBACK_FIX_RECIPE; } });
 Object.defineProperty(exports, "isNodeSqliteAvailable", { enumerable: true, get: function () { return sqlite_adapter_2.isNodeSqliteAvailable; } });
 Object.defineProperty(exports, "isNodeSqliteFts5Available", { enumerable: true, get: function () { return sqlite_adapter_2.isNodeSqliteFts5Available; } });
-Object.defineProperty(exports, "isNativeSqliteAvailable", { enumerable: true, get: function () { return sqlite_adapter_2.isNativeSqliteAvailable; } });
 /**
  * Apply connection-level PRAGMAs. Shared by `initialize` and `open` so the two
  * paths can't drift.
@@ -62,9 +61,9 @@ Object.defineProperty(exports, "isNativeSqliteAvailable", { enumerable: true, ge
  * the lock instead of throwing "database is locked" immediately. See issue #238.
  *
  * The 5s window (was 120s) rides out a normal incremental sync; the old
- * 2-minute wait presented as a frozen, hung agent. With WAL (node:sqlite or
- * better-sqlite3), reads never block on a writer, so this timeout only governs
- * cross-process write contention. The WASM fallback remaps WAL → DELETE.
+ * 2-minute wait presented as a frozen, hung agent. With WAL (node:sqlite),
+ * reads never block on a writer, so this timeout only governs cross-process
+ * write contention. The WASM fallback remaps WAL → DELETE.
  */
 function configureConnection(db) {
     db.pragma('busy_timeout = 5000'); // MUST be first — see above
@@ -593,9 +592,8 @@ class DatabaseConnection {
                 return null;
             }
         }
-        // WASM has no real WAL; mixing node:sqlite with a better-sqlite3 main
-        // connection (e.g. Node 23 where node:sqlite lacks FTS5) corrupts WAL state.
-        if (this.backend !== 'node-sqlite' && this.backend !== 'native') {
+        // WASM has no real WAL — only checkpoint node:sqlite connections.
+        if (this.backend !== 'node-sqlite') {
             return null;
         }
         try {
@@ -605,14 +603,8 @@ class DatabaseConnection {
         let row = null;
         let err = null;
         try {
-          let db = null;
-          if (workerData.backend === 'native') {
-            const Database = require('better-sqlite3');
-            db = new Database(workerData.dbPath);
-          } else {
-            const { DatabaseSync } = require('node:sqlite');
-            db = new DatabaseSync(workerData.dbPath);
-          }
+          const { DatabaseSync } = require('node:sqlite');
+          const db = new DatabaseSync(workerData.dbPath);
           const mode = workerData.mode === 'TRUNCATE' ? 'TRUNCATE' : 'PASSIVE';
           try {
             if (mode === 'TRUNCATE') db.exec('PRAGMA busy_timeout = 2000');
@@ -633,7 +625,7 @@ class DatabaseConnection {
                 try {
                     const worker = new Worker(workerSource, {
                         eval: true,
-                        workerData: { dbPath: this.dbPath, mode, backend: this.backend },
+                        workerData: { dbPath: this.dbPath, mode },
                     });
                     worker.once('message', (m) => {
                         if (m?.err && process.env.HOMEGRAPH_WAL_VALVE_DEBUG) {
@@ -721,14 +713,8 @@ class DatabaseConnection {
             const workerSource = `
         const { workerData, parentPort } = require('node:worker_threads');
         try {
-          let db = null;
-          try {
-            const { DatabaseSync } = require('node:sqlite');
-            db = new DatabaseSync(workerData.dbPath);
-          } catch {
-            const Database = require('better-sqlite3');
-            db = new Database(workerData.dbPath);
-          }
+          const { DatabaseSync } = require('node:sqlite');
+          const db = new DatabaseSync(workerData.dbPath);
           for (const p of workerData.pragmas) { try { db.exec(p); } catch {} }
           try { db.close(); } catch {}
         } catch {}

package/dist/db/queries.d.ts

@@ -268,7 +268,7 @@ export declare class QueryBuilder {
     /**
      * Get nodes by exact qualified name match (uses idx_nodes_qualified_name index)
      */
-    getNodesByQualifiedNameExact(qualifiedName: string): Node[];
+    getNodesByQualifiedNameExact(qualifiedName: string, limit?: number): Node[];
     /**
      * Get nodes by lowercase name match (uses idx_nodes_lower_name expression index)
      */
@@ -349,6 +349,10 @@ export declare class QueryBuilder {
      * Get incoming edges to a node
      */
     getIncomingEdges(targetId: string, kinds?: EdgeKind[], limit?: number): Edge[];
+    /** Bounded local adjacency for evidence search; never load a whole hub into JS.
+     * Known endpoints get a small indexed lookup before the bounded neighbor scan.
+     */
+    getEvidenceEdges(nodeId: string, direction: 'outgoing' | 'incoming', kinds: EdgeKind[], limit: number, preferredIds?: string[]): Edge[];
     /**
      * Find all edges where both source and target are in the given node set.
      * Useful for recovering inter-node connectivity after BFS.

package/dist/db/queries.js

@@ -626,7 +626,7 @@ class QueryBuilder {
         if (misses.length === 0)
             return out;
         // Chunk under SQLite's parameter limit (default 999, raised to 32766
-        // in better-sqlite3 builds — chunk at 500 for safety across both
+        // across node:sqlite / wasm builds — chunk at 500 for safety across both
         // backends and to keep the query plan simple).
         for (let i = 0; i < misses.length; i += SQLITE_PARAM_CHUNK_SIZE) {
             const chunk = misses.slice(i, i + SQLITE_PARAM_CHUNK_SIZE);
@@ -921,7 +921,12 @@ class QueryBuilder {
     /**
      * Get nodes by exact qualified name match (uses idx_nodes_qualified_name index)
      */
-    getNodesByQualifiedNameExact(qualifiedName) {
+    getNodesByQualifiedNameExact(qualifiedName, limit) {
+        if (limit !== undefined) {
+            const cap = Number.isFinite(limit) ? Math.max(1, Math.min(100, Math.floor(limit))) : 25;
+            return this.db.prepare('SELECT * FROM nodes WHERE qualified_name = ? LIMIT ?')
+                .all(qualifiedName, cap).map(rowToNode);
+        }
         if (!this.stmts.getNodesByQualifiedNameExact) {
             this.stmts.getNodesByQualifiedNameExact = this.db.prepare('SELECT * FROM nodes WHERE qualified_name = ?');
         }
@@ -1571,6 +1576,30 @@ class QueryBuilder {
         const rows = this.stmts.getEdgesByTarget.all(targetId);
         return rows.map(rowToEdge);
     }
+    /** Bounded local adjacency for evidence search; never load a whole hub into JS.
+     * Known endpoints get a small indexed lookup before the bounded neighbor scan.
+     */
+    getEvidenceEdges(nodeId, direction, kinds, limit, preferredIds = []) {
+        if (!kinds.length)
+            return [];
+        const cap = Number.isFinite(limit) ? Math.max(1, Math.min(100, Math.floor(limit))) : 25;
+        const column = direction === 'incoming' ? 'target' : 'source';
+        const opposite = direction === 'incoming' ? 'source' : 'target';
+        const kindsSql = kinds.map(() => '?').join(',');
+        const preferred = [...new Set(preferredIds)].slice(0, 4);
+        const base = `SELECT * FROM edges WHERE ${column} = ? AND kind IN (${kindsSql})`;
+        const rows = [];
+        if (preferred.length) {
+            rows.push(...this.db.prepare(`${base} AND ${opposite} IN (${preferred.map(() => '?').join(',')}) LIMIT ?`)
+                .all(nodeId, ...kinds, ...preferred, cap));
+        }
+        if (rows.length < cap) {
+            const omitPreferred = preferred.length ? ` AND ${opposite} NOT IN (${preferred.map(() => '?').join(',')})` : '';
+            rows.push(...this.db.prepare(`${base}${omitPreferred} LIMIT ?`)
+                .all(nodeId, ...kinds, ...preferred, cap - rows.length));
+        }
+        return rows.map(rowToEdge);
+    }
     /**
      * Find all edges where both source and target are in the given node set.
      * Useful for recovering inter-node connectivity after BFS.