homegraph 1.5.7 → 1.5.8

package/CHANGELOG.md

@@ -10,6 +10,21 @@ 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
@@ -19,12 +34,17 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### 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
@@ -219,3 +239,4 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 [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
@@ -356,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/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.

package/dist/db/sqlite-adapter.d.ts

@@ -1,16 +1,12 @@
 /**
  * SQLite Adapter
  *
- * Three-tier selection (first success wins):
+ * Two-tier selection (first success wins):
  *   1. `node:sqlite` (`DatabaseSync`) — real SQLite + WAL + FTS5, Node ≥22.5
  *      (skipped when the build lacks FTS5 — e.g. some Node 23.x official builds)
- *   2. `better-sqlite3` — native addon (optionalDependency)
- *   3. `node-sqlite3-wasm` — last-resort fallback (no WAL; slower / lock-prone)
+ *   2. `node-sqlite3-wasm` — cross-platform fallback (no WAL; slower / lock-prone)
  *
- * Library hosts on Node 22.0–22.4 land on (2) or (3). Node ≥22.5 prefers (1) when
- * FTS5 is present and skips the native build. Override with
- * `HOMEGRAPH_SQLITE_BACKEND=node-sqlite|native|wasm`.
- * optionalDependency `better-sqlite3` is 12.x (Node 22+); wasm remains the last resort.
+ * Override with `HOMEGRAPH_SQLITE_BACKEND=node-sqlite|wasm`.
  */
 export interface SqliteStatement {
     run(...params: any[]): {
@@ -37,11 +33,11 @@ export interface SqliteDatabase {
     readonly open: boolean;
 }
 /** Active SQLite backend after {@link createDatabase}. */
-export type SqliteBackend = 'node-sqlite' | 'native' | 'wasm';
+export type SqliteBackend = 'node-sqlite' | 'wasm';
 /**
  * One-line recovery hint when WASM is active (no WAL — slower / lock-prone).
  */
-export declare const WASM_FALLBACK_FIX_RECIPE: string;
+export declare const WASM_FALLBACK_FIX_RECIPE = "upgrade to Node.js 22.5+ (uses built-in node:sqlite with FTS5), then restart homegraph";
 /**
  * Banner shown to stderr when falling back to WASM.
  */
@@ -49,11 +45,9 @@ export declare function buildWasmFallbackBanner(priorErrors?: string): string;
 /** True when `require('node:sqlite').DatabaseSync` succeeds. */
 export declare function isNodeSqliteAvailable(): boolean;
 export declare function isNodeSqliteFts5Available(): boolean;
-/** True when `require('better-sqlite3')` succeeds. */
-export declare function isNativeSqliteAvailable(): boolean;
 /**
  * Create a database connection.
- * Order: node:sqlite (with FTS5) → better-sqlite3 → node-sqlite3-wasm (unless overridden).
+ * Order: node:sqlite (with FTS5) → node-sqlite3-wasm (unless overridden).
  */
 export declare function createDatabase(dbPath: string, opts?: {
     readOnly?: boolean;

package/dist/db/sqlite-adapter.js

@@ -2,30 +2,23 @@
 /**
  * SQLite Adapter
  *
- * Three-tier selection (first success wins):
+ * Two-tier selection (first success wins):
  *   1. `node:sqlite` (`DatabaseSync`) — real SQLite + WAL + FTS5, Node ≥22.5
  *      (skipped when the build lacks FTS5 — e.g. some Node 23.x official builds)
- *   2. `better-sqlite3` — native addon (optionalDependency)
- *   3. `node-sqlite3-wasm` — last-resort fallback (no WAL; slower / lock-prone)
+ *   2. `node-sqlite3-wasm` — cross-platform fallback (no WAL; slower / lock-prone)
  *
- * Library hosts on Node 22.0–22.4 land on (2) or (3). Node ≥22.5 prefers (1) when
- * FTS5 is present and skips the native build. Override with
- * `HOMEGRAPH_SQLITE_BACKEND=node-sqlite|native|wasm`.
- * optionalDependency `better-sqlite3` is 12.x (Node 22+); wasm remains the last resort.
+ * Override with `HOMEGRAPH_SQLITE_BACKEND=node-sqlite|wasm`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WASM_FALLBACK_FIX_RECIPE = void 0;
 exports.buildWasmFallbackBanner = buildWasmFallbackBanner;
 exports.isNodeSqliteAvailable = isNodeSqliteAvailable;
 exports.isNodeSqliteFts5Available = isNodeSqliteFts5Available;
-exports.isNativeSqliteAvailable = isNativeSqliteAvailable;
 exports.createDatabase = createDatabase;
 /**
  * One-line recovery hint when WASM is active (no WAL — slower / lock-prone).
  */
-exports.WASM_FALLBACK_FIX_RECIPE = 'upgrade to Node.js 22.5+ (uses built-in node:sqlite), or ' +
-    '`xcode-select --install` (macOS) / `apt install build-essential` (Debian/Ubuntu) ' +
-    'then `npm rebuild better-sqlite3`.';
+exports.WASM_FALLBACK_FIX_RECIPE = 'upgrade to Node.js 22.5+ (uses built-in node:sqlite with FTS5), then restart homegraph';
 /**
  * Banner shown to stderr when falling back to WASM.
  */
@@ -33,20 +26,15 @@ function buildWasmFallbackBanner(priorErrors) {
     const sep = '─'.repeat(72);
     const lines = [
         sep,
-        '[HomeGraph] WASM SQLite fallback active (node:sqlite + better-sqlite3 unavailable)',
+        '[HomeGraph] WASM SQLite fallback active (node:sqlite unavailable or lacks FTS5)',
         sep,
         'Indexing and sync will be 5-10x slower than a WAL backend, and concurrent',
-        'reads can hit "database is locked". Prefer Node 22.5+ or better-sqlite3.',
+        'reads can hit "database is locked". Prefer Node.js 22.5 or newer.',
         '',
-        'Fix — use built-in SQLite (best when you can):',
+        'Fix — use built-in SQLite:',
         '  Use Node.js 22.5 or newer, then restart homegraph',
         '',
-        'Fix — native better-sqlite3:',
-        '  macOS:  xcode-select --install && npm rebuild better-sqlite3',
-        '  Linux:  sudo apt install build-essential python3 make && npm rebuild better-sqlite3',
-        '  Any:    npm install better-sqlite3 --save',
-        '',
-        'Verify after fix: `homegraph status` should show Backend: node-sqlite or native.',
+        'Verify after fix: `homegraph status` should show Backend: node-sqlite.',
     ];
     if (priorErrors) {
         lines.push('', `Prior load errors: ${priorErrors}`);
@@ -155,20 +143,9 @@ function isNodeSqliteFts5Available() {
     }
     return cachedNodeSqliteFts5;
 }
-/** True when `require('better-sqlite3')` succeeds. */
-function isNativeSqliteAvailable() {
-    try {
-        // eslint-disable-next-line @typescript-eslint/no-require-imports
-        require('better-sqlite3');
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 /**
  * Wraps Node's built-in `node:sqlite` (`DatabaseSync`) to match the
- * better-sqlite3 interface the rest of the code expects.
+ * statement/database interface the rest of the code expects.
  */
 class NodeSqliteAdapter {
     _db;
@@ -362,10 +339,11 @@ class WasmDatabaseAdapter {
 }
 function resolveBackendOrder() {
     const raw = process.env.HOMEGRAPH_SQLITE_BACKEND?.trim().toLowerCase();
-    if (raw === 'node-sqlite' || raw === 'native' || raw === 'wasm') {
+    if (raw === 'node-sqlite' || raw === 'wasm') {
         return [raw];
     }
-    return ['node-sqlite', 'native', 'wasm'];
+    // Unknown values (including legacy `native`) fall through to the default order.
+    return ['node-sqlite', 'wasm'];
 }
 function tryOpenBackend(backend, dbPath, opts) {
     try {
@@ -379,12 +357,6 @@ function tryOpenBackend(backend, dbPath, opts) {
             }
             return { db: new NodeSqliteAdapter(dbPath, opts), backend: 'node-sqlite' };
         }
-        if (backend === 'native') {
-            // eslint-disable-next-line @typescript-eslint/no-require-imports
-            const Database = require('better-sqlite3');
-            const db = opts?.readOnly ? new Database(dbPath, { readonly: true }) : new Database(dbPath);
-            return { db: db, backend: 'native' };
-        }
         return { db: new WasmDatabaseAdapter(dbPath, opts), backend: 'wasm' };
     }
     catch (error) {
@@ -393,7 +365,7 @@ function tryOpenBackend(backend, dbPath, opts) {
 }
 /**
  * Create a database connection.
- * Order: node:sqlite (with FTS5) → better-sqlite3 → node-sqlite3-wasm (unless overridden).
+ * Order: node:sqlite (with FTS5) → node-sqlite3-wasm (unless overridden).
  */
 function createDatabase(dbPath, opts) {
     const order = resolveBackendOrder();

package/dist/directory.d.ts

@@ -63,7 +63,7 @@ export declare function isInitialized(projectRoot: string): boolean;
  * The returned string is a human phrase that slots into "… looks like {reason}".
  */
 export declare function unsafeIndexRootReason(projectRoot: string): string | null;
-export declare function findNearestHomeGraphRoot(startPath: string): string | null;
+export declare function findNearestHomeGraphRoot(startPath: string, floor?: string): string | null;
 /**
  * Indexed sub-project roots beneath `root` (bounded breadth-first scan). For
  * the monorepo case behind #964: the index lives in a CHILD

package/dist/directory.js

@@ -183,17 +183,41 @@ function unsafeIndexRootReason(projectRoot) {
     }
     return null;
 }
-function findNearestHomeGraphRoot(startPath) {
+function findNearestHomeGraphRoot(startPath, floor) {
+    // A floor (an MCP host's explicit --path / rootUri) bounds the walk: an
+    // ancestor .homegraph above it must not be adopted — a stray ancestor index
+    // hijacks every nested server, whose daemon then indexes the wrong (often
+    // huge) tree and OOMs (spec 0028). Only honored when it contains the start;
+    // a misconfigured floor must not break discovery.
+    const resolveBestEffort = (p) => {
+        try {
+            return fs.realpathSync(path.resolve(p));
+        }
+        catch {
+            return path.resolve(p);
+        }
+    };
+    // Walk the literal chain (returned to the caller in ITS coordinate system);
+    // track the realpath chain in parallel only for the boundary comparison, so
+    // a symlinked prefix (macOS /var vs /private/var) cannot desync the floor.
     let current = path.resolve(startPath);
+    let currentReal = resolveBestEffort(current);
     const root = path.parse(current).root;
+    const floorDir = floor ? resolveBestEffort(floor) : null;
+    const clamped = floorDir !== null &&
+        (currentReal === floorDir || currentReal.startsWith(floorDir + path.sep));
     while (current !== root) {
         if (isInitialized(current)) {
             return current;
         }
+        if (clamped && currentReal === floorDir) {
+            return null; // the floor itself has no index — stop, never look above
+        }
         const parent = path.dirname(current);
         if (parent === current)
             break; // Reached filesystem root
         current = parent;
+        currentReal = path.dirname(currentReal);
     }
     // Check root as well
     if (isInitialized(current)) {

package/dist/extraction/grammars.d.ts

@@ -51,6 +51,8 @@ export declare function isArkModuleJson5(filePath: string): boolean;
  * Idempotent — safe to call multiple times.
  */
 export declare function initGrammars(): Promise<void>;
+/** Filenames copy-assets must ship under dist/extraction/wasm/ (Spec 0031). */
+export declare function vendoredWasmFilenames(): string[];
 /**
  * Pre-read the grammar WASM bytes for an index set, keyed by language. The
  * orchestrator reads each grammar ONCE and hands the bytes to every parse

package/dist/extraction/grammars.js

@@ -47,6 +47,7 @@ exports.isErlangAppFile = isErlangAppFile;
 exports.isPlayRoutesFile = isPlayRoutesFile;
 exports.isArkModuleJson5 = isArkModuleJson5;
 exports.initGrammars = initGrammars;
+exports.vendoredWasmFilenames = vendoredWasmFilenames;
 exports.readGrammarWasmBytes = readGrammarWasmBytes;
 exports.loadGrammarsForLanguages = loadGrammarsForLanguages;
 exports.loadAllGrammars = loadAllGrammars;
@@ -309,13 +310,8 @@ async function initGrammars() {
  * primary constructors natively. Terraform: tree-sitter-wasms does not ship
  * HCL/Terraform at all, so we vendor the prebuilt tree-sitter-terraform.wasm
  * from @tree-sitter-grammars/tree-sitter-hcl 1.2.0 (Apache-2.0) —
- * byte-identical to the npm package's artifact. ArkTS: tree-sitter-wasms
- * doesn't ship it either; we vendor the prebuilt tree-sitter-arkts.wasm from
- * the tree-sitter-arkts 0.2.0 npm package (harmony-contrib/tree-sitter-arkts,
- * MIT) — byte-identical to the npm tarball's artifact. It extends the
- * tree-sitter-javascript grammar the same way tree-sitter-typescript does,
- * adding `struct_declaration` and the `arkui_component_expression` build()
- * DSL. Nix: tree-sitter-wasms doesn't ship it; we vendor a wasm built from
+ * byte-identical to the npm package's artifact. Nix: tree-sitter-wasms doesn't
+ * ship it; we vendor a wasm built from
  * nix-community/tree-sitter-nix @ 3d0173d (MIT) with tree-sitter-cli 0.25.10
  * (`generate` + `build --wasm`, ABI 15 — upstream's checked-in parser.c is
  * still ABI 13; all 54 upstream corpus tests pass on the regenerated parser).
@@ -324,6 +320,10 @@ const VENDORED_WASM_LANGS = new Set([
     'pascal', 'scala', 'lua', 'luau', 'csharp', 'r', 'cfml', 'cfscript', 'cfquery',
     'cobol', 'vbnet', 'erlang', 'terraform', 'nix',
 ]);
+/** Filenames copy-assets must ship under dist/extraction/wasm/ (Spec 0031). */
+function vendoredWasmFilenames() {
+    return [...new Set([...VENDORED_WASM_LANGS].map((lang) => WASM_GRAMMAR_FILES[lang]))].sort();
+}
 /** Absolute path of a language's grammar WASM (vendored or tree-sitter-wasms). */
 function resolveWasmPath(lang) {
     const wasmFile = WASM_GRAMMAR_FILES[lang];

package/dist/graph/evidence-paths.d.ts

@@ -0,0 +1,63 @@
+import type { Edge, EdgeKind, Node } from '../types';
+import type { QueryPlan } from '../search/query-plan';
+export type EvidencePathKind = 'calls' | 'events' | 'state' | 'structure';
+export type EvidenceDirection = 'outgoing' | 'incoming' | 'either';
+export interface EvidencePathGoal {
+    kind: EvidencePathKind;
+    direction: EvidenceDirection;
+    anchorIds: string[];
+    ambiguous: string[];
+    limited: boolean;
+}
+export interface EvidencePath {
+    id: string;
+    nodeIds: string[];
+    edges: Edge[];
+    cost: number;
+    /** Search orientation only; nodeIds and edges always retain actual graph direction. */
+    orientation: 'outgoing' | 'incoming';
+}
+export interface EvidencePathSearch {
+    goal: EvidencePathGoal;
+    paths: EvidencePath[];
+    neighbors: Edge[];
+    missing: Array<{
+        from: string;
+        to: string;
+    }>;
+    stopReason: 'supported' | 'neighbors_only' | 'no_path_in_scope' | 'budget_exhausted' | 'ambiguous_anchors' | 'insufficient_anchors';
+    limitsHit: string[];
+    stats: {
+        adjacencyReads: number;
+        rowsRead: number;
+        nodesVisited: number;
+        durationMs: number;
+    };
+}
+export interface EvidencePathGraph {
+    getNode(id: string): Node | null | undefined;
+    getEdges(id: string, direction: 'outgoing' | 'incoming', kinds: EdgeKind[], limit: number, preferred: string[]): Edge[];
+}
+export declare const EVIDENCE_PATH_LIMITS: {
+    anchors: number;
+    hops: number;
+    reads: number;
+    perNode: number;
+    nodes: number;
+    milliseconds: number;
+};
+export declare function isEvidencePathNode(n: Node): boolean;
+/** Exact names may have been removed by generic search stopwords (e.g. Type.start).
+ * Resolve through the qualified-name index, never by picking a bare-name overload.
+ */
+export declare function completeEvidencePathCandidates(query: string, nodes: Node[], lookup: (qualifiedName: string, limit: number) => Node[], plan?: QueryPlan): Node[];
+/** Resolve only actual candidate identities; a bare homonym never selects the first hit. */
+export declare function resolveEvidencePathGoal(query: string, nodes: Node[], focusIds: Set<string>, plan?: QueryPlan): EvidencePathGoal;
+export declare function evidenceEdgeCost(edge: Edge, goal: EvidencePathGoal): number | null;
+export declare function evidenceEdgeKey(edge: Edge): string;
+/** One bounded search per request. Each orientation follows directed edges throughout. */
+export declare function searchEvidencePaths(graph: EvidencePathGraph, goal: EvidencePathGoal, options?: {
+    now?: () => number;
+    limits?: Partial<typeof EVIDENCE_PATH_LIMITS>;
+}): EvidencePathSearch;
+//# sourceMappingURL=evidence-paths.d.ts.map