homegraph 1.5.6 → 1.5.8

package/dist/mcp/query-cache.js

@@ -23,6 +23,9 @@ exports.normalizeExploreQueryTerms = normalizeExploreQueryTerms;
 exports.buildMcpQueryCacheFingerprint = buildMcpQueryCacheFingerprint;
 exports.buildMcpQueryCacheKey = buildMcpQueryCacheKey;
 const node_crypto_1 = require("node:crypto");
+const query_plan_1 = require("../search/query-plan");
+const PLAN_RELATIONS = new Set(query_plan_1.QUERY_RELATIONS);
+const PLAN_SOURCE_SCOPES = new Set(query_plan_1.QUERY_SOURCE_SCOPES);
 /** Mirrors `getExploreOutputBudget` tier breakpoints — cache-key only. */
 function defaultExploreMaxFiles(fileCount) {
     if (fileCount < 150)
@@ -32,7 +35,7 @@ function defaultExploreMaxFiles(fileCount) {
     return 8;
 }
 /** Bump when cache-key normalization or cached payload shape changes. */
-exports.QUERY_CACHE_FORMAT_VERSION = 1;
+exports.QUERY_CACHE_FORMAT_VERSION = 5;
 const METADATA_INDEX_STAMP = 'query_cache_index_stamp';
 const METADATA_FORMAT_VERSION = 'query_cache_format_version';
 /** Tools that must stay live — never cached. */
@@ -140,7 +143,10 @@ function exploreEnvFingerprint() {
         ? '0'
         : '1';
     const rankMultiterm = process.env.HOMEGRAPH_RANK_NO_MULTITERM === '1' ? '0' : '1';
-    return `linums:${linums}|adaptive:${adaptive}|rankMultiterm:${rankMultiterm}`;
+    const fullSource = process.env.HOMEGRAPH_EXPLORE_FULL_SOURCE === '1' ? '1' : '0';
+    const evidencePacks = process.env.HOMEGRAPH_ARKTS_EVIDENCE_PACKS === '0' ? '0' : '1';
+    const queryPaths = process.env.HOMEGRAPH_ARKTS_QUERY_PATHS === '0' ? '0' : '1';
+    return `linums:${linums}|adaptive:${adaptive}|rankMultiterm:${rankMultiterm}|fullSource:${fullSource}|arktsEvidence:${evidencePacks}|arktsPaths:${queryPaths}`;
 }
 function normalizeString(value) {
     if (typeof value !== 'string')
@@ -152,13 +158,92 @@ function intParam(value, fallback) {
     const n = Number(value);
     return Number.isFinite(n) && n > 0 ? Math.floor(Math.floor(n)) : fallback;
 }
+/**
+ * Project the execution semantics of an internal plan, not its per-call timing.
+ * Ordered queries/steps/anchors preserve direction (A calls B != B calls A).
+ * Explicit projection also keeps telemetry, deadlines and unknown fields out of
+ * keys, and is safe on malformed/cyclic values at a worker or library boundary.
+ */
+function queryPlanFingerprint(value) {
+    const record = (v) => v !== null && typeof v === 'object' && !Array.isArray(v)
+        ? v : undefined;
+    const strings = (v, limit) => {
+        if (!Array.isArray(v) || v.length > limit)
+            return undefined;
+        return v.every(item => typeof item === 'string' && item.length <= 256)
+            ? v : undefined;
+    };
+    const query = (v) => typeof v === 'string' && v.length <= 16_384 ? v : undefined;
+    const validRetrievalFields = (v) => (v.searchTerms === undefined || strings(v.searchTerms, 32) !== undefined)
+        && (v.literalTexts === undefined || strings(v.literalTexts, 16) !== undefined)
+        && (v.relation === undefined || (typeof v.relation === 'string' && PLAN_RELATIONS.has(v.relation)))
+        && (v.sourceScope === undefined || (typeof v.sourceScope === 'string' && PLAN_SOURCE_SCOPES.has(v.sourceScope)));
+    const plan = record(value);
+    if (!plan || !validRetrievalFields(plan))
+        return undefined;
+    if ((typeof plan.version !== 'number' || !Number.isFinite(plan.version))
+        && (typeof plan.version !== 'string' || plan.version.length > 64))
+        return undefined;
+    const originalQuery = query(plan.originalQuery);
+    const canonicalQuery = query(plan.canonicalQuery);
+    const intent = normalizeString(plan.intent);
+    const route = normalizeString(plan.route);
+    const anchors = strings(plan.anchors, 32);
+    const searchTerms = strings(plan.searchTerms, 32);
+    if (originalQuery === undefined || canonicalQuery === undefined || !intent || !route
+        || !anchors || !searchTerms || !Array.isArray(plan.steps) || plan.steps.length > 3)
+        return undefined;
+    const steps = [];
+    for (const value of plan.steps) {
+        const step = record(value);
+        if (!step || !validRetrievalFields(step))
+            return undefined;
+        const id = normalizeString(step.id);
+        const stepQuery = query(step.query);
+        const stepIntent = normalizeString(step.intent);
+        const stepAnchors = strings(step.anchors, 32);
+        const dependsOn = strings(step.dependsOn, 3);
+        if (!id || stepQuery === undefined || !stepIntent || !stepAnchors || !dependsOn)
+            return undefined;
+        steps.push({ id, query: stepQuery, intent: stepIntent, anchors: stepAnchors, dependsOn,
+            searchTerms: strings(step.searchTerms, 32), literalTexts: strings(step.literalTexts, 16),
+            relation: normalizeString(step.relation), sourceScope: normalizeString(step.sourceScope) });
+    }
+    const features = record(plan.features);
+    if (!features || Object.keys(features).length > 64
+        || !Object.values(features).every(v => typeof v === 'boolean'))
+        return undefined;
+    return stableJson({
+        version: plan.version, originalQuery, canonicalQuery, intent, route,
+        taskContext: query(plan.taskContext),
+        anchors, searchTerms, steps, features,
+        literalTexts: strings(plan.literalTexts, 16), relation: normalizeString(plan.relation),
+        sourceScope: normalizeString(plan.sourceScope),
+        source: typeof plan.source === 'string' ? plan.source : undefined,
+        confidence: typeof plan.confidence === 'number' || typeof plan.confidence === 'string'
+            ? plan.confidence : undefined,
+    });
+}
 /** Build the pre-hash fingerprint string for a tool + args pair. */
 function buildMcpQueryCacheFingerprint(toolName, args, fileCount) {
     const parts = [toolName.replace(/^homegraph_/, '')];
     switch (toolName) {
         case 'homegraph_explore': {
             const query = normalizeString(args.query) ?? '';
-            parts.push(`terms:${normalizeExploreQueryTerms(query).join(',')}`);
+            const plan = queryPlanFingerprint(args.__homegraphQueryPlan);
+            if (plan) {
+                parts.push(`plan:${plan}`);
+            }
+            else {
+                // Preserve order-independent legacy keys for calls without a valid plan.
+                parts.push(`terms:${normalizeExploreQueryTerms(query).join(',')}`);
+                const taskContext = normalizeString(args.taskContext);
+                if (taskContext)
+                    parts.push(`taskContext:${taskContext.slice(0, 4000)}`);
+            }
+            const indexState = normalizeString(args.__homegraphQueryIndexState);
+            if (indexState)
+                parts.push(`indexState:${JSON.stringify(indexState)}`);
             if (args.maxFiles != null) {
                 parts.push(`maxFiles:${intParam(args.maxFiles, 12)}`);
             }
@@ -173,6 +258,8 @@ function buildMcpQueryCacheFingerprint(toolName, args, fileCount) {
         }
         case 'homegraph_search': {
             parts.push(`query:${(normalizeString(args.query) ?? '').toLowerCase()}`);
+            // Search can reuse the compact ArkTS renderer as an existing fast path.
+            parts.push(exploreEnvFingerprint());
             if (args.kind != null) {
                 const kind = args.kind === 'type' ? 'type_alias' : String(args.kind);
                 parts.push(`kind:${kind}`);

package/dist/mcp/query-worker.d.ts

@@ -2,7 +2,7 @@
  * Query worker thread — issue: concurrent MCP tool calls starve the daemon.
  *
  * The shared daemon serves every session on ONE event loop with synchronous
- * SQLite (better-sqlite3 / wasm). `codegraph_explore` is CPU-heavy (FTS + RWR/personalized-
+ * SQLite (node:sqlite / wasm). `codegraph_explore` is CPU-heavy (FTS + RWR/personalized-
  * PageRank + impact + output building) stitched together by microtask `await`s,
  * so N concurrent explores keep the microtask queue continuously full and
  * starve the macrotask phases — timers AND socket I/O. The transport freezes:

package/dist/mcp/query-worker.js

@@ -3,7 +3,7 @@
  * Query worker thread — issue: concurrent MCP tool calls starve the daemon.
  *
  * The shared daemon serves every session on ONE event loop with synchronous
- * SQLite (better-sqlite3 / wasm). `codegraph_explore` is CPU-heavy (FTS + RWR/personalized-
+ * SQLite (node:sqlite / wasm). `codegraph_explore` is CPU-heavy (FTS + RWR/personalized-
  * PageRank + impact + output building) stitched together by microtask `await`s,
  * so N concurrent explores keep the microtask queue continuously full and
  * starve the macrotask phases — timers AND socket I/O. The transport freezes:

package/dist/mcp/server-instructions.d.ts

@@ -1,12 +1,7 @@
 /**
- * Server-level instructions emitted in the MCP `initialize` response.
- *
- * Single source of truth for agent-facing tool guidance (issue #529).
- * Edit here — not installer prompts or eval harness prompts.
- *
- * Keep this short: long essays are low-salience and rarely change tool choice.
- * Prefer concrete habits (query shape, which tool, when to stop).
+ * MCP initialize 中的统一工具指引；工具描述必须遵守相同的按需策略。
+ * 仅调整检索选择，不改变索引、查询语义或编码任务的验收要求。
  */
-export declare const SERVER_INSTRUCTIONS = "# HomeGraph \u2014 structural locator for THIS repo\n\nLocal symbol graph (defs / calls / imports / files). Use it to **coarse-locate** in-repo symbols (`file:line` + short source), then answer. Not general Q&A, not SDK docs.\n\n## Call first (do not Grep/Glob/Read first)\n\nWill you **explain or edit in-repo code**? \u2192 `homegraph_explore` **once** with the user task as `query` (Chinese OK; add English Type / `Type.member` / `@kit` / `@ohos` tokens when you know them).\n\nAlready know **one** exact symbol? Prefer smaller tools: `homegraph_callers` / `homegraph_callees` / `homegraph_node`. Spelling unknown \u2192 `homegraph_search` last.\n\nFor a narrow inventory, call `homegraph_usages` (where-used), `homegraph_modules` (named module deps/cycles), or `homegraph_native` (NAPI exports). Existing clients may keep calling `homegraph_explore`: high-confidence shapes route to the same bounded handlers.\n\nEngineering overview / module\u2192file map (including while the full index is still building) \u2192 `homegraph_project`.\n\n**Must explore-first:** how/mechanism wiring, named Type / `.member`, in-repo `@kit`/`@ohos` **usages**, deps/cycles, NAPI / `.d.ts` wrap sites, pre-edit orientation.\n\nArkUI V1\u2194V2 / state-decorator migration on a named component \u2192 `homegraph_arkui_migrate` once (not explore stitching).\n\n## How to write `query`\n\n- Put **concrete anchors** in the bag: `FooManager`, `BarEvent`, `Type.member`, `feature/foo`, `@kit.X`.\n- Map Chinese entities to English symbol stems when you can (`\u8BBE\u7F6E`\u2192`Setting`, `\u65B0\u5EFA`\u2192`New`) \u2014 search/explore cluster `Entity` / `EntityManager` / `EntityViewModel`.\n- Keep **intent words** with the Type (`\u6765\u6E90` / `\u5206\u53D1` / `\u4F9D\u8D56` / `NAPI` / `\u9A71\u52A8`) \u2014 bare Type alone may drop survey routing.\n- Multi-app monorepo: pass `projectPath` to the app root; ignore sibling-app paths as noise.\n\n## After one explore\n\n- Returned line-numbered source = **already Read** for those symbols \u2014 do not re-Grep/Read/node the **same** symbols.\n- **Coarse locate / ANSWER NOW** \u2192 answer/edit from anchors; do not verify with a Grep storm.\n- **Partial locator** \u2192 **ONE** tighter follow-up with the named **Next anchor** only \u2014 never a paraphrase or a different Type (server refuses). After Partial: **no** `homegraph_callers`/`callees`; at most **one** `homegraph_node`. A **second** Partial \u2192 stop HomeGraph; ONE narrow Grep then answer \u2014 never a repo-wide glob/Read storm.\n- Busy/deadline \u2192 retry **once** tighter; then answer from anchors (narrow Grep OK for residuals).\n\nPrefer smallest tool when the name is known: callers/callees/node \u226A explore \u226A search. Prefer **one** Type-wide inventory explore over fanning `homegraph_callers` per method. Session fuse: **\u22642** `homegraph_explore` per project; after Partial follow-ups must name the **Next anchor**; **\u22641** `homegraph_node` after Partial \u2014 further calls are refused.\n\n## Do not call HomeGraph\n\nRuntime Skip is a short blacklist (everything else is served if you call):\n\n- Topic \u2192 file list with no Type/file basename\n- Literal / layout copy hunts with no Type/file/`@kit`/`@ohos`\n- Pure existence / concept-compare with no graph anchors\n- Official website/docs only \u00B7 scaffold empty project \u00B7 git/blame/diff \u00B7 media/binary inventories\n\n`@kit` / OHOS **API usage in this repo** \u2192 explore (not Skip). Feature **catalogs** of an SDK \u2192 SDK docs, not HomeGraph.\n\nIf a tool returns **Skip HomeGraph**, stop \u2014 do not retry `homegraph_*`.\n\n## Tips\n\n- Empty callers/callees = **edges not indexed**, not \u201Cmissing symbol\u201D \u2014 use the definition anchor; narrow Grep for registration if needed.\n- **Staleness banner** \u2014 Read only listed edited files.\n- **Not indexed** \u2014 use built-ins; user runs `homegraph init` (you do not).\n";
-export declare const SERVER_INSTRUCTIONS_NO_ROOT_INDEX = "# HomeGraph \u2014 per-project (pass projectPath)\n\nPass `projectPath` to a folder that has `.homegraph/`.\n\n**Call first:** explain/edit in-repo code \u2192 `homegraph_explore` with task keywords (no Grep-first). Named Type / `Type.member` / usages / deps / NAPI / `@kit` \u2192 explore.\n\nNarrow inventories may call `homegraph_usages`, `homegraph_modules`, or `homegraph_native` directly; pass the same `projectPath`.\n\n**Skip:** topic file-lists, concept compares, literal hunts, git history, media. No index \u2192 Read/Grep/Glob; user runs `homegraph init`.\n\n**Query habit:** Chinese OK; add English Type/`@kit` tokens when known. Explore = coarse locate. Partial \u2192 one tighter follow-up with a concrete name from the list. ONE narrow Grep OK for residual unindexed wiring \u2014 not a Grep storm.\n";
+export declare const SERVER_INSTRUCTIONS = "# HomeGraph \u2014 optional structural evidence for this repo\n\n## When to call (path-first, bash-first)\n\nUse ordinary bash/search/read tools first for repository paths, symbols, literal strings and local changes. Skip HomeGraph when those tools provide sufficient evidence, including for difficult implementation tasks. A known path can be read directly; an adequate source result does not need a second graph lookup.\n\nHomeGraph is optional. Use it only for a concrete unresolved relationship that benefits from graph evidence: cross-file state/event propagation, callers/callees, module dependencies or ArkTS-to-native registration. Name the missing relation and use anchors from the current task or source. There is no mandatory number of bash searches before a useful graph query.\n\nChoose the smallest available tool for that gap:\n- Exact usage/reference locations \u2192 `homegraph_usages`; callers/callees \u2192 the corresponding tool.\n- Named module dependencies/cycles \u2192 `homegraph_modules`; native exports/registration \u2192 `homegraph_native`.\n- One missing symbol body \u2192 `homegraph_node`; prefer direct read if its path is already known.\n- An unresolved cross-symbol mechanism \u2192 `homegraph_explore`. Do not use it for routine pre-edit orientation, a literal search, or to re-confirm source already found with bash.\n- ArkUI migration analysis \u2192 `homegraph_arkui_migrate` when that analysis is needed; SDK contracts \u2192 project declarations or SDK documentation.\n\nDo not call explore after a focused tool already answered the relation. Keep working directly once the edit location and affected behavior are sufficiently supported. Task difficulty and file count alone do not require graph use.\n\n## Query and recovery\n\nWrite one focused sentence: requested action + target + known anchors + unresolved relation + preservation constraints. Use the full public task as `taskContext` when needed. Keep UI labels verbatim; use exact symbols from the task or source instead of inventing names or piling up generic keywords. Use returned repository-relative paths without reconstructing an experiment directory; a path refusal requires valid in-repo relocation, not broader permissions.\n\nA project map is navigation, not proof of a located feature. Preserve requested product/module scope and verify each candidate before editing. Start with one focused graph request; recover only a named missing body/relation. Budget: \u22642 `homegraph_explore` attempts per project, \u22641 focused depth recovery; existing runtime budgets may be tighter. These are ceilings, never a required sequence. If evidence is still missing, use targeted bash/search/read and continue implementation. Do not expand into unrelated files merely to exhaust a budget.\n\n\n- ArkTS evidence packs keep complete declarations and the source dependencies of displayed static relations together. Gaps identify omitted, stale or unindexed evidence; inspect only a gap relevant to the task. A static link does not prove runtime ordering or value propagation, and a complete declaration does not prove its enclosing call conditions.\n- ArkTS path evidence follows typed, directed relations between named anchors within a bounded search. A provided path includes intermediate declarations and registration sites. Check its goal and stop reason; no path in scope does not prove no relationship. Qualify ambiguous symbols with their owning type or file.\n- Reuse complete, unchanged, line-numbered source ranges already visible. An outline, path list, truncated body or SDK declaration cannot replace missing implementation evidence. A slice hash identifies that excerpt, not the whole file. Refresh affected ranges after edits.\n- An empty edge set means the relation may be unindexed, not absent. For partial, stale or irrelevant results, inspect the exact missing source with scoped search/read. After a query adds no evidence, change the method or scope rather than paraphrasing the same explore.\n- Retrieval completion is not task completion. Continue the requested edits and validation; check the original task's behavior and preservation constraints. Build success alone does not establish functional correctness.\n\nNo index \u2192 use ordinary tools; indexing is managed by the host. Do not run HomeGraph initialization as part of solving the task.\n";
+export declare const SERVER_INSTRUCTIONS_NO_ROOT_INDEX = "# HomeGraph \u2014 optional per-project evidence\n\nPass `projectPath` to an already indexed folder with `.homegraph/`. No index \u2192 use ordinary tools; indexing is managed by the host.\n\n## When to call (path-first, bash-first)\n\nUse ordinary bash/search/read tools first for repository paths, symbols, literal strings and local changes. Skip HomeGraph when those tools provide sufficient evidence, including for difficult implementation tasks. A known path can be read directly; an adequate source result does not need a second graph lookup.\n\nHomeGraph is optional. Use it only for a concrete unresolved relationship that benefits from graph evidence: cross-file state/event propagation, callers/callees, module dependencies or ArkTS-to-native registration. Name the missing relation and use anchors from the current task or source. There is no mandatory number of bash searches before a useful graph query.\n\nChoose the smallest available tool for that gap:\n- Exact usage/reference locations \u2192 `homegraph_usages`; callers/callees \u2192 the corresponding tool.\n- Named module dependencies/cycles \u2192 `homegraph_modules`; native exports/registration \u2192 `homegraph_native`.\n- One missing symbol body \u2192 `homegraph_node`; prefer direct read if its path is already known.\n- An unresolved cross-symbol mechanism \u2192 `homegraph_explore`. Do not use it for routine pre-edit orientation, a literal search, or to re-confirm source already found with bash.\n- ArkUI migration analysis \u2192 `homegraph_arkui_migrate` when that analysis is needed; SDK contracts \u2192 project declarations or SDK documentation.\n\nDo not call explore after a focused tool already answered the relation. Keep working directly once the edit location and affected behavior are sufficiently supported. Task difficulty and file count alone do not require graph use.\n\n## Query and recovery\n\nWrite one focused sentence: requested action + target + known anchors + unresolved relation + preservation constraints. Use the full public task as `taskContext` when needed. Keep UI labels verbatim; use exact symbols from the task or source instead of inventing names or piling up generic keywords. Use returned repository-relative paths without reconstructing an experiment directory; a path refusal requires valid in-repo relocation, not broader permissions.\n\nA project map is navigation, not proof of a located feature. Preserve requested product/module scope and verify each candidate before editing. Start with one focused graph request; recover only a named missing body/relation. Budget: \u22642 `homegraph_explore` attempts per project, \u22641 focused depth recovery; existing runtime budgets may be tighter. These are ceilings, never a required sequence. If evidence is still missing, use targeted bash/search/read and continue implementation. Do not expand into unrelated files merely to exhaust a budget.\n\n\n- ArkTS evidence packs keep complete declarations and the source dependencies of displayed static relations together. Gaps identify omitted, stale or unindexed evidence; inspect only a gap relevant to the task. A static link does not prove runtime ordering or value propagation, and a complete declaration does not prove its enclosing call conditions.\n- ArkTS path evidence follows typed, directed relations between named anchors within a bounded search. A provided path includes intermediate declarations and registration sites. Check its goal and stop reason; no path in scope does not prove no relationship. Qualify ambiguous symbols with their owning type or file.\n- Reuse complete, unchanged, line-numbered source ranges already visible. An outline, path list, truncated body or SDK declaration cannot replace missing implementation evidence. A slice hash identifies that excerpt, not the whole file. Refresh affected ranges after edits.\n- An empty edge set means the relation may be unindexed, not absent. For partial, stale or irrelevant results, inspect the exact missing source with scoped search/read. After a query adds no evidence, change the method or scope rather than paraphrasing the same explore.\n- Retrieval completion is not task completion. Continue the requested edits and validation; check the original task's behavior and preservation constraints. Build success alone does not establish functional correctness.\n\n";
 //# sourceMappingURL=server-instructions.d.ts.map

package/dist/mcp/server-instructions.js

@@ -1,78 +1,51 @@
 "use strict";
 /**
- * Server-level instructions emitted in the MCP `initialize` response.
- *
- * Single source of truth for agent-facing tool guidance (issue #529).
- * Edit here — not installer prompts or eval harness prompts.
- *
- * Keep this short: long essays are low-salience and rarely change tool choice.
- * Prefer concrete habits (query shape, which tool, when to stop).
+ * MCP initialize 中的统一工具指引；工具描述必须遵守相同的按需策略。
+ * 仅调整检索选择，不改变索引、查询语义或编码任务的验收要求。
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SERVER_INSTRUCTIONS_NO_ROOT_INDEX = exports.SERVER_INSTRUCTIONS = void 0;
-exports.SERVER_INSTRUCTIONS = `# HomeGraph — structural locator for THIS repo
-
-Local symbol graph (defs / calls / imports / files). Use it to **coarse-locate** in-repo symbols (\`file:line\` + short source), then answer. Not general Q&A, not SDK docs.
-
-## Call first (do not Grep/Glob/Read first)
-
-Will you **explain or edit in-repo code**? → \`homegraph_explore\` **once** with the user task as \`query\` (Chinese OK; add English Type / \`Type.member\` / \`@kit\` / \`@ohos\` tokens when you know them).
-
-Already know **one** exact symbol? Prefer smaller tools: \`homegraph_callers\` / \`homegraph_callees\` / \`homegraph_node\`. Spelling unknown → \`homegraph_search\` last.
-
-For a narrow inventory, call \`homegraph_usages\` (where-used), \`homegraph_modules\` (named module deps/cycles), or \`homegraph_native\` (NAPI exports). Existing clients may keep calling \`homegraph_explore\`: high-confidence shapes route to the same bounded handlers.
-
-Engineering overview / module→file map (including while the full index is still building) → \`homegraph_project\`.
-
-**Must explore-first:** how/mechanism wiring, named Type / \`.member\`, in-repo \`@kit\`/\`@ohos\` **usages**, deps/cycles, NAPI / \`.d.ts\` wrap sites, pre-edit orientation.
-
-ArkUI V1↔V2 / state-decorator migration on a named component → \`homegraph_arkui_migrate\` once (not explore stitching).
-
-## How to write \`query\`
-
-- Put **concrete anchors** in the bag: \`FooManager\`, \`BarEvent\`, \`Type.member\`, \`feature/foo\`, \`@kit.X\`.
-- Map Chinese entities to English symbol stems when you can (\`设置\`→\`Setting\`, \`新建\`→\`New\`) — search/explore cluster \`Entity\` / \`EntityManager\` / \`EntityViewModel\`.
-- Keep **intent words** with the Type (\`来源\` / \`分发\` / \`依赖\` / \`NAPI\` / \`驱动\`) — bare Type alone may drop survey routing.
-- Multi-app monorepo: pass \`projectPath\` to the app root; ignore sibling-app paths as noise.
-
-## After one explore
-
-- Returned line-numbered source = **already Read** for those symbols — do not re-Grep/Read/node the **same** symbols.
-- **Coarse locate / ANSWER NOW** → answer/edit from anchors; do not verify with a Grep storm.
-- **Partial locator** → **ONE** tighter follow-up with the named **Next anchor** only — never a paraphrase or a different Type (server refuses). After Partial: **no** \`homegraph_callers\`/\`callees\`; at most **one** \`homegraph_node\`. A **second** Partial → stop HomeGraph; ONE narrow Grep then answer — never a repo-wide glob/Read storm.
-- Busy/deadline → retry **once** tighter; then answer from anchors (narrow Grep OK for residuals).
-
-Prefer smallest tool when the name is known: callers/callees/node ≪ explore ≪ search. Prefer **one** Type-wide inventory explore over fanning \`homegraph_callers\` per method. Session fuse: **≤2** \`homegraph_explore\` per project; after Partial follow-ups must name the **Next anchor**; **≤1** \`homegraph_node\` after Partial — further calls are refused.
-
-## Do not call HomeGraph
-
-Runtime Skip is a short blacklist (everything else is served if you call):
-
-- Topic → file list with no Type/file basename
-- Literal / layout copy hunts with no Type/file/\`@kit\`/\`@ohos\`
-- Pure existence / concept-compare with no graph anchors
-- Official website/docs only · scaffold empty project · git/blame/diff · media/binary inventories
+const SOURCE_AND_VALIDATION = `
+- ArkTS evidence packs keep complete declarations and the source dependencies of displayed static relations together. Gaps identify omitted, stale or unindexed evidence; inspect only a gap relevant to the task. A static link does not prove runtime ordering or value propagation, and a complete declaration does not prove its enclosing call conditions.
+- ArkTS path evidence follows typed, directed relations between named anchors within a bounded search. A provided path includes intermediate declarations and registration sites. Check its goal and stop reason; no path in scope does not prove no relationship. Qualify ambiguous symbols with their owning type or file.
+- Reuse complete, unchanged, line-numbered source ranges already visible. An outline, path list, truncated body or SDK declaration cannot replace missing implementation evidence. A slice hash identifies that excerpt, not the whole file. Refresh affected ranges after edits.
+- An empty edge set means the relation may be unindexed, not absent. For partial, stale or irrelevant results, inspect the exact missing source with scoped search/read. After a query adds no evidence, change the method or scope rather than paraphrasing the same explore.
+- Retrieval completion is not task completion. Continue the requested edits and validation; check the original task's behavior and preservation constraints. Build success alone does not establish functional correctness.
+`;
+const ON_DEMAND = `## When to call (path-first, bash-first)
 
-\`@kit\` / OHOS **API usage in this repo** → explore (not Skip). Feature **catalogs** of an SDK → SDK docs, not HomeGraph.
+Use ordinary bash/search/read tools first for repository paths, symbols, literal strings and local changes. Skip HomeGraph when those tools provide sufficient evidence, including for difficult implementation tasks. A known path can be read directly; an adequate source result does not need a second graph lookup.
 
-If a tool returns **Skip HomeGraph**, stop — do not retry \`homegraph_*\`.
+HomeGraph is optional. Use it only for a concrete unresolved relationship that benefits from graph evidence: cross-file state/event propagation, callers/callees, module dependencies or ArkTS-to-native registration. Name the missing relation and use anchors from the current task or source. There is no mandatory number of bash searches before a useful graph query.
 
-## Tips
+Choose the smallest available tool for that gap:
+- Exact usage/reference locations → \`homegraph_usages\`; callers/callees → the corresponding tool.
+- Named module dependencies/cycles → \`homegraph_modules\`; native exports/registration → \`homegraph_native\`.
+- One missing symbol body → \`homegraph_node\`; prefer direct read if its path is already known.
+- An unresolved cross-symbol mechanism → \`homegraph_explore\`. Do not use it for routine pre-edit orientation, a literal search, or to re-confirm source already found with bash.
+- ArkUI migration analysis → \`homegraph_arkui_migrate\` when that analysis is needed; SDK contracts → project declarations or SDK documentation.
 
-- Empty callers/callees = **edges not indexed**, not “missing symbol” — use the definition anchor; narrow Grep for registration if needed.
-- **Staleness banner** — Read only listed edited files.
-- **Not indexed** — use built-ins; user runs \`homegraph init\` (you do not).
+Do not call explore after a focused tool already answered the relation. Keep working directly once the edit location and affected behavior are sufficiently supported. Task difficulty and file count alone do not require graph use.
 `;
-exports.SERVER_INSTRUCTIONS_NO_ROOT_INDEX = `# HomeGraph — per-project (pass projectPath)
+const QUERY = `## Query and recovery
 
-Pass \`projectPath\` to a folder that has \`.homegraph/\`.
+Write one focused sentence: requested action + target + known anchors + unresolved relation + preservation constraints. Use the full public task as \`taskContext\` when needed. Keep UI labels verbatim; use exact symbols from the task or source instead of inventing names or piling up generic keywords. Use returned repository-relative paths without reconstructing an experiment directory; a path refusal requires valid in-repo relocation, not broader permissions.
 
-**Call first:** explain/edit in-repo code → \`homegraph_explore\` with task keywords (no Grep-first). Named Type / \`Type.member\` / usages / deps / NAPI / \`@kit\` → explore.
+A project map is navigation, not proof of a located feature. Preserve requested product/module scope and verify each candidate before editing. Start with one focused graph request; recover only a named missing body/relation. Budget: ≤2 \`homegraph_explore\` attempts per project, ≤1 focused depth recovery; existing runtime budgets may be tighter. These are ceilings, never a required sequence. If evidence is still missing, use targeted bash/search/read and continue implementation. Do not expand into unrelated files merely to exhaust a budget.
+`;
+exports.SERVER_INSTRUCTIONS = `# HomeGraph — optional structural evidence for this repo
 
-Narrow inventories may call \`homegraph_usages\`, \`homegraph_modules\`, or \`homegraph_native\` directly; pass the same \`projectPath\`.
+${ON_DEMAND}
+${QUERY}
+${SOURCE_AND_VALIDATION}
+No index → use ordinary tools; indexing is managed by the host. Do not run HomeGraph initialization as part of solving the task.
+`;
+exports.SERVER_INSTRUCTIONS_NO_ROOT_INDEX = `# HomeGraph — optional per-project evidence
 
-**Skip:** topic file-lists, concept compares, literal hunts, git history, media. No index → Read/Grep/Glob; user runs \`homegraph init\`.
+Pass \`projectPath\` to an already indexed folder with \`.homegraph/\`. No index → use ordinary tools; indexing is managed by the host.
 
-**Query habit:** Chinese OK; add English Type/\`@kit\` tokens when known. Explore = coarse locate. Partial → one tighter follow-up with a concrete name from the list. ONE narrow Grep OK for residual unindexed wiring — not a Grep storm.
+${ON_DEMAND}
+${QUERY}
+${SOURCE_AND_VALIDATION}
 `;
 //# sourceMappingURL=server-instructions.js.map

package/dist/mcp/session.js

@@ -253,7 +253,10 @@ class MCPSession {
             // Kick off engine init in the background. If another session in the
             // same daemon already opened the project, `ensureInitialized` is a
             // ~free no-op — N concurrent clients pay exactly one open.
-            this.resolvePromise = this.engine.ensureInitialized(explicitPath);
+            // explicitPath is a DECLARED root (rootUri / workspaceFolders / --path),
+            // so it also bounds the walk-up (spec 0028): a stray ancestor .homegraph
+            // must not hijack the session.
+            this.resolvePromise = this.engine.ensureInitialized(explicitPath, explicitPath);
         }
     }
     async handleToolsList(request) {
@@ -329,9 +332,10 @@ class MCPSession {
                 return;
         }
         // Last resort: walk from the best candidate (sync open). Picks up
-        // projects that appeared after the server started.
+        // projects that appeared after the server started. The hint (server
+        // --path) is a declaration → floor; bare cwd is not.
         const candidate = hint ?? process.cwd();
-        this.engine.retryInitializeSync(candidate);
+        this.engine.retryInitializeSync(candidate, hint ?? undefined);
     }
     /**
      * Ask the client for its workspace root via `roots/list` and open the
@@ -339,11 +343,15 @@ class MCPSession {
      */
     async initFromRoots() {
         let target = process.cwd();
+        // Only a real roots/list answer is a client DECLARATION of the workspace
+        // root — the cwd fallbacks are not, and keep the git-style walk-up.
+        let declared = false;
         try {
             const result = await this.transport.request('roots/list', undefined, ROOTS_LIST_TIMEOUT_MS);
             const rootPath = firstRootPath(result);
             if (rootPath) {
                 target = rootPath;
+                declared = true;
             }
             else {
                 process.stderr.write('[HomeGraph MCP] Client returned no workspace roots; falling back to process cwd.\n');
@@ -353,7 +361,7 @@ class MCPSession {
             const msg = err instanceof Error ? err.message : String(err);
             process.stderr.write(`[HomeGraph MCP] roots/list request failed (${msg}); falling back to process cwd.\n`);
         }
-        await this.engine.ensureInitialized(target);
+        await this.engine.ensureInitialized(target, declared ? target : undefined);
     }
 }
 exports.MCPSession = MCPSession;

package/dist/mcp/source-slice-identity.d.ts

@@ -0,0 +1,3 @@
+/** 只标识实际返回的片段，不冒充整个文件版本或任务覆盖率。 */
+export declare function sourceSliceIdentity(path: string, start: number, source: string): string;
+//# sourceMappingURL=source-slice-identity.d.ts.map

package/dist/mcp/source-slice-identity.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sourceSliceIdentity = sourceSliceIdentity;
+const node_crypto_1 = require("node:crypto");
+/** 只标识实际返回的片段，不冒充整个文件版本或任务覆盖率。 */
+function sourceSliceIdentity(path, start, source) {
+    const end = start + source.split('\n').length - 1;
+    const digest = (0, node_crypto_1.createHash)('sha256').update(source, 'utf8').digest('hex').slice(0, 16);
+    return `Source slice: ${path}:${start}-${end}; excerpt-sha256=${digest}. Excerpt only; refresh after edits.`;
+}
+//# sourceMappingURL=source-slice-identity.js.map

package/dist/mcp/tools.d.ts

@@ -202,6 +202,8 @@ export interface ToolResult {
         text: string;
     }>;
     isError?: boolean;
+    /** Compact diagnostics for hosts/evaluators; never credentials or source dumps. */
+    _meta?: Record<string, unknown>;
     /**
      * Internal: what an explore call emitted (CG-17). {@link ToolHandler.execute}
      * records it into the calling session's state and deletes it before the result
@@ -315,6 +317,23 @@ export declare class ToolHandler {
      * allowlist so a trimmed surface is reflected in ListTools.
      */
     getTools(): ToolDefinition[];
+    /**
+     * Per-repo suffix appended to homegraph_explore's description (Spec 0027).
+     *
+     * fileCount === 0 must not read as "this project is empty": hosts snapshot
+     * tools/list once at connect (#964), and an auto-init that is still building
+     * reports 0 at that instant. Field evidence (DevEco Code bench, 3 sessions,
+     * zero homegraph calls): agents read "make at most 1 calls for this project
+     * (0 files indexed)" as terminal — "homegraph isn't indexed for this
+     * project" — and permanently fell back to Read/Grep even though the index
+     * completed seconds later. Mirror maybeDeepToolPhaseGate's success-shaped
+     * guidance so the frozen description and the live call-time response tell
+     * the same story: failed build → say so (indexing is the user's call, so
+     * the agent relays it); still building → point at homegraph_project and
+     * retry; genuinely empty → honest empty note. Only fileCount > 0 carries a
+     * call budget — there is nothing to budget over an unbuilt index.
+     */
+    private exploreSuffix;
     /**
      * Get HomeGraph instance for a project
      *
@@ -422,6 +441,10 @@ export declare class ToolHandler {
      * once the session's one allowed depth drill is spent.
      */
     private tryDepthToolFuse;
+    /** A repeated query is duplicate evidence only while its source is unchanged. */
+    private shouldRefuseRepeatedEvidence;
+    /** Same bounded fingerprint check for repeat protection and cached source packs. */
+    private areEvidenceFilesCurrent;
     /** Count a successful depth-tool call when the latest explore was Partial. */
     private noteDepthToolUse;
     /**
@@ -474,9 +497,8 @@ export declare class ToolHandler {
      */
     private dispatchTool;
     /**
-     * Gate symbol/graph tools while auto-init is still on the fast map or
-     * background full index (and no nodes exist yet). Success-shaped guidance —
-     * never isError — so agents keep using HomeGraph.
+     * Gate symbol/graph tools by product index state (Spec 0032).
+     * Success-shaped guidance — never isError — so agents keep using HomeGraph.
      */
     private maybeDeepToolPhaseGate;
     private handleSearch;
@@ -612,14 +634,24 @@ export declare class ToolHandler {
      * Avoids fat multi-body compact that hits the soft deadline (D60).
      */
     private buildMultiTypeDependencySection;
-    /**
-     * Main-thread fast path for inventory surveys — skips the worker queue.
-     */
+    /** Exact validation for model-proposed names: a fuzzy hit is not proof. */
+    private isExactPlanAnchor;
+    /** Bind only declarations returned by this step, not input or global fuzzy hits. */
+    private locatedPlanBindings;
+    private withQueryPlanDiagnostics;
+    /** Select once; legacy section builders consume the same canonical query/features. */
+    private tryPlannedFastPath;
+    /** Internal execution only: no recursive MCP calls, model requests or new deadline. */
+    private executePlannedStep;
+    private executeQueryPlan;
+    /** Main-thread fast path for inventory surveys — skips the worker queue. */
     private tryFastPathResult;
     /** Conservative compatibility router: ambiguous mechanism queries stay broad. */
     private specializedExploreRouteForQuery;
     /** Run exactly one bounded survey family and expose the selected route. */
     private runSpecializedExploreRoute;
+    /** Directed file import witnesses for an explicit module-import relation. */
+    private renderModuleImports;
     /** Usage sites for a bare symbol bag, including non-call textual references. */
     private buildBareSymbolUsageSection;
     private trySpecializedExploreRoute;
@@ -630,9 +662,9 @@ export declare class ToolHandler {
      * Fast inventory-only explore — skips findRelevantContext for survey/caller/dependency queries.
      */
     private tryFastInventoryExplore;
-    /**
-     * Render a compact symbol-bounded slice of one file (lightweight mechanism path).
-     */
+    /** Pack already-located ArkTS evidence before legacy windowing can cut it. */
+    private tryArktsEvidenceExplore;
+    /** Render a compact symbol-bounded slice on the legacy mechanism path. */
     private renderLightMechanismSource;
     /**
      * Lightweight mechanism explore — seed entry symbols + flow spine, skip
@@ -740,6 +772,8 @@ export declare class ToolHandler {
      * tax on small projects while earning its keep on large ones.
      */
     private handleExplore;
+    /** Render literal witnesses before graph-heavy sections, including unindexed UI. */
+    private renderLiteralSource;
     /**
      * An explore response plus the record of what it emitted (CG-17). The record
      * rides the result only as far as {@link execute}, which files it into the