homegraph 1.6.0 → 1.6.2

package/dist/mcp/tools.js

@@ -1,14 +1,10 @@
 "use strict";
-/**
- * MCP Tool Definitions
- *
- * Defines the tools exposed by the HomeGraph MCP server.
- */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ToolHandler = exports.tools = exports.PathRefusalError = exports.GraphSourcesDisabledError = exports.NotIndexedError = void 0;
+exports.ToolHandler = exports.DEFAULT_MCP_TOOL_SHORT_NAMES = exports.tools = exports.PathRefusalError = exports.GraphSourcesDisabledError = exports.NotIndexedError = void 0;
 exports.__setLoadHomeGraphForTests = __setLoadHomeGraphForTests;
 exports.normalizeQuerySpelling = normalizeQuerySpelling;
 exports.getExploreBudget = getExploreBudget;
+exports.formatExploreCallBudgetNote = formatExploreCallBudgetNote;
 exports.getExploreOutputBudget = getExploreOutputBudget;
 exports.tightenExploreBudgetForQuery = tightenExploreBudgetForQuery;
 exports.exploreLocatorDigestEnabled = exploreLocatorDigestEnabled;
@@ -20,11 +16,17 @@ exports.formatHarmonySeamNotes = formatHarmonySeamNotes;
 exports.formatStaleBanner = formatStaleBanner;
 exports.formatStaleFooter = formatStaleFooter;
 exports.formatDegradedBanner = formatDegradedBanner;
+exports.resolveMcpToolAllowlist = resolveMcpToolAllowlist;
+exports.shortMcpToolNamesEnabled = shortMcpToolNamesEnabled;
+exports.canonicalizeMcpToolName = canonicalizeMcpToolName;
 exports.getStaticTools = getStaticTools;
 exports.extractBareUsageSymbols = extractBareUsageSymbols;
 exports.queryAsBareSymbolInventory = queryAsBareSymbolInventory;
 exports.hasPositiveAnswerNowDirective = hasPositiveAnswerNowDirective;
 exports.reconcilePartialAnswerNow = reconcilePartialAnswerNow;
+const evidence_audit_1 = require("./evidence-audit");
+const implementation_context_1 = require("./implementation-context");
+const request_contract_1 = require("../search/request-contract");
 const query_pool_1 = require("./query-pool");
 const source_slice_identity_1 = require("./source-slice-identity");
 const evidence_rendering_1 = require("./evidence-rendering");
@@ -310,6 +312,14 @@ function getExploreBudget(fileCount) {
         return 4;
     return 5;
 }
+/**
+ * Cooldown shown on `homegraph_explore` when the project is indexed.
+ * Matches {@link exploreCooldownSeconds}. Output tiers stay on {@link getExploreBudget}.
+ */
+function formatExploreCallBudgetNote(fileCount) {
+    const files = Math.max(0, fileCount).toLocaleString();
+    return `Wait ${(0, explore_repeat_guard_1.exploreCooldownSeconds)()} seconds after homegraph_explore returns before calling it again (${files} files indexed).`;
+}
 function getExploreOutputBudget(fileCount) {
     // Tiered budget, scaled to project size. The budget is a CEILING (relevance
     // still gates WHAT is included), and it MUST stay under the agent's INLINE
@@ -885,11 +895,17 @@ function formatDegradedBanner(reason) {
         (reason ? `\n  Reason: ${reason}` : ''));
 }
 /**
- * Common projectPath property for cross-project queries
+ * projectPath property descriptions — kept in sync with whether the field is
+ * in `inputSchema.required`. The optional text is the module-level default
+ * (session has a bound root). {@link withRequiredProjectPath} swaps in the
+ * required text when there is no default project, so schema and prose agree.
  */
+const PROJECT_PATH_DESC_OPTIONAL = 'Absolute path to the project to query (or any directory inside it) — homegraph uses the nearest .homegraph/ index at or above that path. Omit to use this session\'s default project. Pass it to query a second codebase, or when the server root has no index of its own (e.g. a monorepo where only sub-projects are indexed, so there is no default project).';
+const PROJECT_PATH_DESC_REQUIRED = 'Required. Absolute path to the project to query (or any directory inside it) — homegraph uses the nearest .homegraph/ index at or above that path. This session has no default project, so every call must pass projectPath (e.g. a monorepo sub-project with its own .homegraph/, or any already-indexed folder).';
+/** Common projectPath property for cross-project queries (optional / default-project sessions). */
 const projectPathProperty = {
     type: 'string',
-    description: 'Absolute path to the project to query (or any directory inside it) — homegraph uses the nearest .homegraph/ index at or above that path. Omit to use this session\'s default project. Pass it to query a second codebase, or when the server root has no index of its own (e.g. a monorepo where only sub-projects are indexed, so there is no default project).',
+    description: PROJECT_PATH_DESC_OPTIONAL,
 };
 /**
  * EVERY homegraph tool is query-only: it reads the pre-built index and never
@@ -909,10 +925,11 @@ const READ_ONLY_ANNOTATIONS = {
     openWorldHint: false,
 };
 /**
- * All HomeGraph MCP tools
+ * All HomeGraph MCP tool definitions (handlers stay registered).
  *
- * Prefer the smallest tool that answers: callers/node for one named symbol,
- * explore for multi-file flows. Skip HomeGraph entirely for topic file-lists,
+ * Default tools/list is the slim pair in `DEFAULT_MCP_TOOL_SHORT_NAMES`
+ * (explore / project). Opt into the full catalog with
+ * `HOMEGRAPH_MCP_TOOLS=all`. Skip HomeGraph entirely for topic file-lists,
  * concept compares, SDK catalogs, and literal greps.
  *
  * All tools support cross-project queries via the optional `projectPath` parameter.
@@ -1181,16 +1198,15 @@ exports.tools = [
     },
     {
         name: 'homegraph_explore',
-        description: 'Optional graph evidence for a concrete unresolved cross-symbol mechanism in THIS repo. Required: `query`. ' +
+        description: 'Default locator when the task touches existing code in THIS repo. Required: `query`. ' +
+            'Open alone (no parallel grep/glob/read in the same step) with feature/component/symbol keywords; `taskContext` = the requirement. ' +
             'For module/route-profile **paths** and engineering overview use homegraph_project first (not this tool). ' +
-            'Use ordinary bash/search/read for paths, symbols, literal strings and local changes; continue editing when that evidence suffices. ' +
-            'Do not call for routine pre-edit orientation or merely because implementation is difficult. ' +
-            'For a missing usage, dependency/cycle or native-registration relation, use ' +
-            'homegraph_usages, homegraph_modules, or homegraph_native instead. ' +
+            'Do NOT skip because the index might still be building — call anyway. ' +
+            'Located ArkTS code may include render scope, imported types, module configuration, indexed SDK signatures and control-state gaps. ' +
             'Returns call paths and compact line-numbered source (Harmony route_map queries may lead with Registration sources; form/shortcuts queries may lead with Capability profiles; element/string.json literals may lead with Resource hits + optional bound .ets anchors; Seam notes may flag stubs). ArkTS symbol evidence uses complete declarations and bounded directed paths with intermediate source dependencies; explicit Gaps and stop reasons name omitted or unverified evidence. Qualify ambiguous symbols by owning type or file. State the missing relation with known anchors, requested action, scope and constraints; taskContext can carry the full task. ' +
             'Reuse unchanged complete ranges; refresh missing, edited or truncated evidence. ' +
             'No new evidence → change to a targeted source inspection, not a paraphrased explore. ' +
-            'Partial/busy → at most one focused recovery for the named gap; budgets are ceilings, not required calls. ' +
+            `After this tool returns, wait ${(0, explore_repeat_guard_1.exploreCooldownSeconds)()} seconds before calling it again. ` +
             'Retrieval completion is not task completion: continue implementation and required validation.',
         inputSchema: {
             type: 'object',
@@ -1199,7 +1215,7 @@ exports.tools = [
                     type: 'string',
                     description: 'Required. For pre-edit orientation or how/mechanism: pass the user task or domain keywords (page/module/feature words). ' +
                         'For named flows, include Type / Type.member / component names. For @kit mechanism/flow, include module/export tokens; ' +
-                        'use homegraph_usages for a narrow import/usage inventory, not SDK catalogs.',
+                        'not SDK feature catalogs.',
                 },
                 taskContext: {
                     type: 'string',
@@ -1391,11 +1407,12 @@ exports.tools = [
     },
 ];
 /**
- * Return `defs` with `projectPath` marked `required` in each tool's inputSchema.
+ * Return `defs` with `projectPath` marked `required` in each tool's inputSchema
+ * and with a matching property description (no "Omit…" wording).
  *
  * Used for the NO-DEFAULT-PROJECT tool surface (issue #993): when the MCP server
  * has no default project to fall back to — a gateway server started outside any
- * repo, or a monorepo root whose `.codegraph/` indexes live only in sub-projects
+ * repo, or a monorepo root whose `.homegraph/` indexes live only in sub-projects
  * — every call MUST carry an explicit `projectPath`, so the schema should say so.
  * A `required` field is a HIGH-salience channel (MCP clients surface and often
  * validate it), unlike the instructions text the reporter found too weak to stop
@@ -1404,23 +1421,90 @@ exports.tools = [
  *
  * Pure: clones each tool's schema rather than mutating the shared module-level
  * `tools` array (reused by every session and the static surface). A tool that
- * doesn't expose projectPath, or already requires it, is returned untouched;
- * explore's `['query']` becomes `['query', 'projectPath']`, and a tool with no
- * `required` list (status/files) gains `['projectPath']`.
+ * doesn't expose projectPath is returned untouched; explore's `['query']`
+ * becomes `['query', 'projectPath']`, and a tool with no `required` list
+ * (status/files) gains `['projectPath']`. The property description is always
+ * swapped to {@link PROJECT_PATH_DESC_REQUIRED} so it cannot contradict
+ * `required`.
  */
 function withRequiredProjectPath(defs) {
     return defs.map((tool) => {
-        if (!tool.inputSchema.properties.projectPath)
+        const prop = tool.inputSchema.properties.projectPath;
+        if (!prop)
             return tool;
         const required = tool.inputSchema.required ?? [];
-        if (required.includes('projectPath'))
-            return tool;
+        const nextRequired = required.includes('projectPath')
+            ? required
+            : [...required, 'projectPath'];
         return {
             ...tool,
-            inputSchema: { ...tool.inputSchema, required: [...required, 'projectPath'] },
+            inputSchema: {
+                ...tool.inputSchema,
+                properties: {
+                    ...tool.inputSchema.properties,
+                    projectPath: { ...prop, description: PROJECT_PATH_DESC_REQUIRED },
+                },
+                required: nextRequired,
+            },
         };
     });
 }
+/**
+ * Default MCP tools/list surface (product slim). Handlers for other tools remain
+ * in-tree; restore the full catalog with `HOMEGRAPH_MCP_TOOLS=all` (or `*`), or
+ * name a comma list (e.g. `explore,node,search,arkui_migrate`).
+ */
+exports.DEFAULT_MCP_TOOL_SHORT_NAMES = ['explore', 'project'];
+/** Resolve the exposed-tool allowlist from env (default = product slim pair). */
+function resolveMcpToolAllowlist(raw = process.env.HOMEGRAPH_MCP_TOOLS) {
+    if (!raw || !raw.trim()) {
+        return new Set(exports.DEFAULT_MCP_TOOL_SHORT_NAMES);
+    }
+    const trimmed = raw.trim();
+    if (trimmed === '*' || /^all$/i.test(trimmed))
+        return 'all';
+    const set = new Set(trimmed.split(',').map((s) => s.trim().replace(/^homegraph_/, '')).filter(Boolean));
+    return set.size ? set : new Set(exports.DEFAULT_MCP_TOOL_SHORT_NAMES);
+}
+function filterToolsByAllowlist(defs, allow) {
+    if (allow === 'all')
+        return defs;
+    return defs.filter((t) => allow.has(t.name.replace(/^homegraph_/, '')));
+}
+/**
+ * Product hosts that prefix MCP tools with the server name (e.g. DevEco Code
+ * → `homegraph_` + tool name) set `HOMEGRAPH_MCP_SHORT_TOOL_NAMES=1` so
+ * tools/list exposes `explore` / `project` instead of `homegraph_explore`.
+ * After the host prefix, the model-visible name is still `homegraph_explore`.
+ * Cursor / Claude leave this unset and keep the canonical `homegraph_*` names.
+ */
+function shortMcpToolNamesEnabled(raw = process.env.HOMEGRAPH_MCP_SHORT_TOOL_NAMES) {
+    const v = (raw ?? '').trim().toLowerCase();
+    return v === '1' || v === 'true' || v === 'yes';
+}
+const CANONICAL_TOOL_NAMES = new Set(exports.tools.map((t) => t.name));
+/**
+ * Map a tools/call name to the canonical `homegraph_*` form.
+ * Accepts both short (`explore`) and long (`homegraph_explore`) so hosts that
+ * list short names (or still pass the long name) both work.
+ */
+function canonicalizeMcpToolName(name) {
+    if (!name)
+        return name;
+    if (name.startsWith('homegraph_'))
+        return name;
+    const canonical = `homegraph_${name}`;
+    return CANONICAL_TOOL_NAMES.has(canonical) ? canonical : name;
+}
+/** Clone defs with `homegraph_` stripped from each tool name (list surface only). */
+function withShortToolNames(defs) {
+    if (!shortMcpToolNamesEnabled())
+        return defs;
+    return defs.map((t) => ({
+        ...t,
+        name: t.name.replace(/^homegraph_/, ''),
+    }));
+}
 /**
  * Allowlist-filtered tool definitions WITHOUT an engine — the static surface the
  * proxy answers `tools/list` with before any project is open. Mirrors
@@ -1428,12 +1512,7 @@ function withRequiredProjectPath(defs) {
  * note in a description only adds once `cg` is loaded; the schemas are static).
  */
 function getStaticTools() {
-    const raw = process.env.HOMEGRAPH_MCP_TOOLS ?? process.env.HOMEGRAPH_MCP_TOOLS;
-    if (!raw || !raw.trim()) {
-        return exports.tools;
-    }
-    const allow = new Set(raw.split(',').map(s => s.trim().replace(/^homegraph_/, '').replace(/^homegraph_/, '')).filter(Boolean));
-    return allow.size ? exports.tools.filter(t => allow.has(t.name.replace(/^homegraph_/, ''))) : exports.tools;
+    return withShortToolNames(filterToolsByAllowlist(exports.tools, resolveMcpToolAllowlist()));
 }
 /** Prose that reads like an identifier but never names a symbol worth scanning. */
 const BARE_USAGE_STOPWORDS = new Set([
@@ -1697,26 +1776,20 @@ class ToolHandler {
         return this.cg !== null;
     }
     /**
-     * Optional allowlist of exposed tools, parsed from the HOMEGRAPH_MCP_TOOLS
-     * env var (comma-separated short names, e.g. "explore,search,node").
-     * Unset/empty → every tool is exposed. Set → only the listed tools are
-     * exposed. Lets an operator (or an A/B harness) trim the tool surface
-     * without rebuilding the client config; the ablated tool is then truly
-     * absent from ListTools rather than merely denied on call.
+     * Optional allowlist of exposed tools, parsed from HOMEGRAPH_MCP_TOOLS.
+     * Unset/empty → product slim default (`explore`, `project`).
+     * `all` / `*` → full catalog. Comma list → only those short names.
      * Matching is on the short form, so "node" and "homegraph_node" both work.
      */
     toolAllowlist() {
-        const raw = process.env.HOMEGRAPH_MCP_TOOLS ?? process.env.HOMEGRAPH_MCP_TOOLS;
-        if (!raw || !raw.trim())
-            return null;
-        const short = (s) => s.trim().replace(/^homegraph_/, '');
-        const set = new Set(raw.split(',').map(short).filter(Boolean));
-        return set.size ? set : null;
+        return resolveMcpToolAllowlist();
     }
-    /** Whether a tool name passes the HOMEGRAPH_MCP_TOOLS allowlist (if any). */
+    /** Whether a tool name passes the HOMEGRAPH_MCP_TOOLS allowlist. */
     isToolAllowed(name) {
         const allow = this.toolAllowlist();
-        return !allow || allow.has(name.replace(/^homegraph_/, ''));
+        if (allow === 'all')
+            return true;
+        return allow.has(name.replace(/^homegraph_/, ''));
     }
     /**
      * Get tool definitions with dynamic descriptions based on project size.
@@ -1726,11 +1799,7 @@ class ToolHandler {
      */
     getTools() {
         const allow = this.toolAllowlist();
-        // No explicit allowlist → expose every defined tool. An allowlist trims
-        // the surface to only the listed short names.
-        let visible = allow
-            ? exports.tools.filter(t => allow.has(t.name.replace(/^homegraph_/, '')))
-            : exports.tools;
+        let visible = filterToolsByAllowlist(exports.tools, allow);
         // No default project loaded → no-root-index case (#993): a gateway server
         // started outside any repo, or a monorepo root whose indexes live in
         // sub-projects. With nothing to fall back to, EVERY call needs an explicit
@@ -1742,32 +1811,16 @@ class ToolHandler {
         // IS open we leave projectPath optional (below): a bare call falls back to
         // it, exactly as in the common single-project launch.
         if (!this.cg)
-            return withRequiredProjectPath(visible);
+            return withShortToolNames(withRequiredProjectPath(visible));
         try {
             const stats = this.cg.getStats();
-            // Tiny-repo tool gating: on projects under TINY_REPO_FILE_THRESHOLD
-            // files, only expose the core trio (search, node, explore) — one
-            // below even the 4-tool default: at this scale callers, too, reduces
-            // to one grep. (Historical note: the audit below ran when context and
-            // trace still existed; its "5 core tools" are today's trio.)
+            // Tiny-repo tool gating applies only when the host asked for the full
+            // catalog (`HOMEGRAPH_MCP_TOOLS=all`). The product default is already the
+            // slim pair; an explicit comma allowlist is left untouched.
             //
-            // n=2 audits ruled out cutting below 5 tools:
-            // - 3-tool gate (search + context + trace): cost regressed on
-            //   cobra/ky/sinatra. The agent fell back to raw Reads to cover
-            //   what homegraph_node + homegraph_explore would have answered.
-            // - 1-tool gate (search only): catastrophic regression — express
-            //   went from -43% WIN to +107% LOSS. With only search, the agent
-            //   can't navigate the call graph structurally and reads everything.
-            //
-            // 5 is the empirical lower bound. Tools beyond search/context/
-            // node/explore/trace pay overhead that the agent doesn't recoup
-            // on tiny-repo flow questions.
-            // ITER4: raise threshold 150 → 500 so single-file frameworks
-            // (sinatra at 159, slim_framework around 200) also get the
-            // 5-tool surface. The empirical 5-tool floor was set on <150
-            // probes; iter3 measurement showed sinatra is structurally the
-            // SAME problem as cobra (single-file WITHOUT-arm Read wins),
-            // so it deserves the same gating.
+            // Historical note: n=2 audits ruled out cutting below ~5 tools on the
+            // *full* catalog for tiny OSS repos (search+node+explore+…). That trim
+            // still matters when someone opts into `all` on a <500-file tree.
             const TINY_REPO_FILE_THRESHOLD = 500;
             const TINY_REPO_CORE_TOOLS = new Set([
                 'homegraph_explore',
@@ -1776,12 +1829,12 @@ class ToolHandler {
                 'homegraph_diff_impact',
                 'homegraph_project',
             ]);
-            // An explicit host selection overrides the default size-based surface.
-            // Otherwise small ArkTS repos silently lose requested specialized tools.
-            if (!allow && stats.fileCount < TINY_REPO_FILE_THRESHOLD) {
+            const envRaw = (process.env.HOMEGRAPH_MCP_TOOLS ?? '').trim();
+            const askedForFullCatalog = allow === 'all' && (/^all$/i.test(envRaw) || envRaw === '*');
+            if (askedForFullCatalog && stats.fileCount < TINY_REPO_FILE_THRESHOLD) {
                 visible = visible.filter(t => TINY_REPO_CORE_TOOLS.has(t.name));
             }
-            return visible.map(tool => {
+            return withShortToolNames(visible.map(tool => {
                 if (tool.name === 'homegraph_explore') {
                     return {
                         ...tool,
@@ -1789,10 +1842,10 @@ class ToolHandler {
                     };
                 }
                 return tool;
-            });
+            }));
         }
         catch {
-            return visible;
+            return withShortToolNames(visible);
         }
     }
     /**
@@ -1808,12 +1861,12 @@ class ToolHandler {
      * 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.
+     * retry; genuinely empty → honest empty note. Only fileCount > 0 carries the
+     * return cooldown — there is nothing to cool down over an unbuilt index.
      */
     exploreSuffix(fileCount) {
         if (fileCount > 0) {
-            return `Budget: make at most ${getExploreBudget(fileCount)} calls for this project (${fileCount.toLocaleString()} files indexed).`;
+            return formatExploreCallBudgetNote(fileCount);
         }
         const cg = this.cg;
         if (cg) {
@@ -2272,6 +2325,8 @@ class ToolHandler {
      * it (the CLI does) and explore behaves exactly as before, untracked.
      */
     async execute(toolName, args, sessionState) {
+        // Short list names (`explore`) and canonical (`homegraph_explore`) both work.
+        toolName = canonicalizeMcpToolName(toolName);
         const requestStartedAt = Date.now();
         const result = await this.executeCore(toolName, args, sessionState, requestStartedAt);
         this.traceToolCall(toolName, args, result, requestStartedAt);
@@ -2401,7 +2456,8 @@ class ToolHandler {
             // would re-serve the first call's full source and defeat CG-18 dedup.
             const skipCacheForSession = toolName === 'homegraph_explore' && !!sessionState;
             const requestPlan = readQueryPlan(args);
-            const cacheEnabled = !skipCacheForSession && requestPlan?.source !== 'llm'
+            const cacheEnabled = !skipCacheForSession && !(toolName === 'homegraph_explore' && process.env.HOMEGRAPH_ARKTS_EVIDENCE_LOG === '1') && requestPlan?.source !== 'llm'
+                && !(requestPlan?.requestContract && ((0, request_contract_1.accuracyTargetsEnabled)() || (0, request_contract_1.accuracyCoverageEnabled)()))
                 && !requestPlan?.telemetry.fallbackReason && (0, query_cache_1.isMcpQueryCacheEnabled)() && (0, query_cache_1.isCacheableMcpTool)(toolName);
             let cacheKey;
             let cacheQueries;
@@ -2423,7 +2479,7 @@ class ToolHandler {
                     const cached = cacheIndex.getEntry(cacheQueries, cacheKey);
                     const packMeta = cached?._meta?.homegraphEvidencePacks;
                     const cachedFiles = cached?._meta?.homegraphEvidence?.files;
-                    if (cached && (!packMeta || (packMeta.status === 'complete'
+                    if (cached && (!packMeta || (packMeta.status === 'complete' && !packMeta.implementationContext?.length
                         && this.areEvidenceFilesCurrent(cachedFiles ?? [], cacheCg.getProjectRoot())))) {
                         const diagnosed = this.withQueryPlanDiagnostics(cached, args, true);
                         const withWorktree = this.withWorktreeNotice(diagnosed, projectPath);
@@ -3920,7 +3976,7 @@ class ToolHandler {
             '',
             ...notes,
             '',
-            '> These sites choose their call target at runtime (registry / bus / reflection) — the site shown IS where the flow continues. To follow it, run homegraph_explore or homegraph_node on a candidate; source for the sites above is included below.',
+            '> These sites choose their call target at runtime (registry / bus / reflection) — the site shown IS where the flow continues. To follow it, run homegraph_explore on a candidate; source for the sites above is included below.',
             '',
         ].join('\n');
     }
@@ -5161,7 +5217,7 @@ class ToolHandler {
         else {
             lines.push('> **Partial locator** — related writers / sibling Managers above are anchors, not a full answer. ' +
                 'ONE tighter explore with a named Type, or ONE narrow Grep for `@ohos` if still missing — ' +
-                'do **not** fan out `homegraph_node` / callers. Do **not** ANSWER NOW from local cache helpers.');
+                'do **not** fan out callers. Do **not** ANSWER NOW from local cache helpers.');
         }
         lines.push('');
         return { section: lines.join('\n'), edgeCount, sdkImportCount, strongCount };
@@ -5266,7 +5322,7 @@ class ToolHandler {
                     '**Event types → Manager / handler sites**',
                     '',
                     '> **Partial locator** — no event Type/enum exports indexed for the named anchors. '
-                        + '`homegraph_node` / ONE explore on the Event Type file, or ONE Grep for enum members / '
+                        + 'ONE explore on the Event Type file, or ONE Grep for enum members / '
                         + '`case` branches — not a repo-wide storm. Do **not** ANSWER NOW.',
                     '',
                 ].join('\n'),
@@ -5507,7 +5563,7 @@ class ToolHandler {
             lines.push('- No Manager import/use sites indexed for these event types.');
             lines.push('');
             lines.push('> **Partial locator** — event anchors above only. '
-                + '`homegraph_node` the Event file or ONE Grep for handler/`case` branches — do **not** ANSWER NOW as a full dispatch map.');
+                + 'ONE Grep for handler/`case` branches — do **not** ANSWER NOW as a full dispatch map.');
         }
         else {
             for (const h of ranked.slice(0, 24)) {
@@ -5533,7 +5589,7 @@ class ToolHandler {
             }
             else {
                 lines.push('> **Partial locator** — handler files are anchors, but enum-member coverage may be incomplete. '
-                    + '`homegraph_node` the Event Type / ONE Grep for members or `case` — do **not** repo-storm; do **not** ANSWER NOW as a full map.');
+                    + 'ONE Grep for members or `case` — do **not** repo-storm; do **not** ANSWER NOW as a full map.');
             }
         }
         lines.push('');
@@ -5687,13 +5743,13 @@ class ToolHandler {
         const hasExtends = extendsHits.length > 0;
         if (!hasGraph && !hasExtends) {
             lines.push('> **Partial locator** — Type files above are anchors. '
-                + '`homegraph_node` / `homegraph_callees` one Type at a time; do **not** ANSWER NOW as a full graph.');
+                + '`homegraph_callees` one Type at a time; do **not** ANSWER NOW as a full graph.');
         }
         else {
             lines.push('> Multi-Type dependency inventory — **ANSWER NOW** from locations'
                 + (hasExtends ? ' + `extends` bases' : '')
                 + (hasGraph ? ' + import/caller edges' : '')
-                + ' above; only `homegraph_node` one Type if a body detail is still missing.');
+                + ' above; one tighter explore if a body detail is still missing.');
         }
         lines.push('');
         return { section: lines.join('\n'), hitCount: locs.length + edges.length + extendsHits.length };
@@ -5744,7 +5800,7 @@ class ToolHandler {
                     ...prior, version: plan.version, source: plan.source, intent: plan.intent, route: plan.route,
                     confidence: plan.confidence,
                     plannerSeeds: { anchors: plan.anchors, searchTerms: plan.searchTerms, literalTexts: plan.literalTexts,
-                        sourceScope: plan.sourceScope, relation: plan.relation },
+                        sourceScope: plan.sourceScope, relation: plan.relation, requestContract: plan.requestContract },
                     hasTaskContext: !!plan.taskContext,
                     matchedFeatures: Object.entries(plan.features).filter(([, matched]) => matched).map(([name]) => name).slice(0, 12),
                     planningMs: plan.telemetry.durationMs, durationMs: Math.max(plan.telemetry.durationMs, Date.now() - started),
@@ -5769,6 +5825,10 @@ class ToolHandler {
         if (plan.route === 'usages' || plan.route === 'modules' || plan.route === 'native') {
             return this.runSpecializedExploreRoute(plan.route, cg, query, root, plan);
         }
+        // Constrained ArkTS retrieval needs the full, verified-source renderer.
+        if (plan.requestContract && ((0, request_contract_1.accuracyTargetsEnabled)() || (0, request_contract_1.accuracyCoverageEnabled)())
+            && plan.sourceScope !== 'sdk' && cg.getFiles().some(f => /\.ets$/i.test(f.path)))
+            return null;
         // These legacy paths re-extract seeds from text and cannot consume bound
         // node identity / step hints. Model general/flow plans use full explore;
         // rule/default and specialized routes retain their existing fast behavior.
@@ -6269,9 +6329,9 @@ class ToolHandler {
                     soft
                         ? `Named-Type dependency inventory — **${multi.hitCount}** locator hit(s). `
                             + '**Partial locator** — locations above; ONE tighter explore with a named Type, '
-                            + 'or ONE narrow Grep — do **not** fan out `homegraph_node` / callees.'
+                            + 'or ONE narrow Grep — do **not** fan out callees.'
                         : `Named-Type dependency inventory — **${multi.hitCount}** locator hit(s). `
-                            + '**ANSWER NOW** from locations + cross links; one `homegraph_node` only if a body detail is still missing.',
+                            + '**ANSWER NOW** from locations + cross links; one tighter explore only if a body detail is still missing.',
                     '',
                     multi.section,
                 ].join('\n'));
@@ -6629,20 +6689,58 @@ class ToolHandler {
         if (!nodes.some(n => /\.ets$/i.test(n.filePath) && !n.filePath.startsWith('ohos-sdk:')))
             return null;
         const budget = getExploreOutputBudget(cg.getStats().fileCount);
-        const queryPaths = process.env.HOMEGRAPH_ARKTS_QUERY_PATHS !== '0';
+        const constrained = !!plan?.requestContract && ((0, request_contract_1.accuracyTargetsEnabled)() || (0, request_contract_1.accuracyCoverageEnabled)());
+        const queryPaths = (!constrained || plan?.intent === 'flow' || !!plan?.bindings?.length) && process.env.HOMEGRAPH_ARKTS_QUERY_PATHS !== '0';
         if (queryPaths)
             nodes = (0, evidence_paths_1.completeEvidencePathCandidates)(query, nodes, (name, limit) => cg.getQueryBuilder().getNodesByQualifiedNameExact(name, limit), plan);
+        if ((0, implementation_context_1.implementationContextEnabled)()) {
+            const boundIds = new Set(focusIds);
+            nodes = nodes.map(n => {
+                if (n.kind !== 'struct')
+                    return n;
+                const component = cg.getNodesInFile(n.filePath).find(c => c.kind === 'component' && c.name === n.name && c.startLine === n.startLine);
+                if (component && boundIds.has(n.id))
+                    boundIds.add(component.id);
+                return component ?? n;
+            });
+            focusIds = boundIds;
+        }
         const pathSearch = !queryPaths ? undefined : (0, evidence_paths_1.searchEvidencePaths)({
             getNode: id => cg.getNode(id),
-            getEdges: (id, direction, kinds, limit, preferred) => cg.getQueryBuilder().getEvidenceEdges(id, direction, kinds, limit, preferred),
+            getEdges: (id, direction, kinds, limit, preferred) => {
+                const read = (nodeId) => cg.getQueryBuilder().getEvidenceEdges(nodeId, direction, kinds, limit, preferred);
+                if (!(0, implementation_context_1.implementationContextEnabled)())
+                    return read(id);
+                const owner = cg.getNode(id);
+                const aliases = owner && ['struct', 'component'].includes(owner.kind)
+                    ? cg.getNodesInFile(owner.filePath).filter(n => ['struct', 'component'].includes(n.kind) && n.name === owner.name
+                        && n.startLine === owner.startLine && n.endLine === owner.endLine).slice(0, 2) : [];
+                const canonical = (nodeId) => {
+                    const n = cg.getNode(nodeId);
+                    if (!n || n.kind !== 'struct')
+                        return nodeId;
+                    return cg.getNodesInFile(n.filePath).find(c => c.kind === 'component' && c.name === n.name
+                        && c.startLine === n.startLine && c.endLine === n.endLine)?.id ?? nodeId;
+                };
+                // ArkAnalyzer stores struct/component roles for the same declaration. Project
+                // their ownership edges to one identity; this is not a new runtime call.
+                const edges = (aliases.length ? aliases.flatMap(n => read(n.id)) : read(id)).map(e => ({ ...e,
+                    source: canonical(e.source), target: canonical(e.target) })).filter(e => e.source !== e.target);
+                return [...new Map(edges.map(e => [JSON.stringify([e.source, e.target, e.kind, e.metadata]), e])).values()].slice(0, limit);
+            },
         }, (0, evidence_paths_1.resolveEvidencePathGoal)(query, nodes, focusIds, plan));
         const result = (0, arkts_evidence_packs_1.buildArktsEvidencePacks)(cg, { projectRoot, query, nodes, focusIds,
-            maxChars: Math.min(budget.maxOutputChars, maxChars ?? budget.maxOutputChars), maxFiles, pathSearch });
+            maxChars: Math.min(budget.maxOutputChars, maxChars ?? budget.maxOutputChars), maxFiles, pathSearch, requestContract: plan?.requestContract,
+            sdkModule: cg.getGraphSources() === 'project' || cg.getGraphSources() === 'none' ? undefined : module => {
+                const nodes = cg.getQueryBuilder().getOhosApiModuleNodes(module);
+                return nodes.length ? { nodes, version: cg.getOhosApiBinding()?.version ?? 'unknown' } : undefined;
+            } });
         if (!result)
             return null;
+        const audit = (0, evidence_audit_1.recordEvidencePack)(projectRoot, { query, requestContract: plan?.requestContract }, result);
         // The pack renderer already supplies neutral guidance and exact source bytes.
         return { content: [{ type: 'text', text: result.text }], [explore_session_state_1.EXPLORE_EMISSION_KEY]: result.emission,
-            _meta: { homegraphEvidencePacks: result.metadata } };
+            _meta: { homegraphEvidencePacks: result.metadata, ...(audit !== 'disabled' ? { homegraphEvidenceAudit: audit } : {}) } };
     }
     /** Render a compact symbol-bounded slice on the legacy mechanism path. */
     renderLightMechanismSource(projectRoot, filePath, nodes, maxChars) {
@@ -6876,7 +6974,7 @@ class ToolHandler {
                 : '> **Partial locator** — Manager / domain inventory below are anchors, not a full mechanism closure. '
                     + 'Pick **ONE** concrete `*Manager` / next-hop name from the list for a tighter explore — '
                     + 'do **not** re-explore a paraphrase of the same keyword bag. '
-                    + 'At most one `homegraph_node` after Partial; prefer ONE narrow Grep for unlisted wiring — not a repo storm. '
+                    + 'Prefer ONE narrow Grep for unlisted wiring — not a repo storm. '
                     + 'Do **not** ANSWER NOW yet.',
             '',
             `Mechanism anchors: **${seedIds.size}** symbol(s) — lightweight explore (seed + flow spine).`,
@@ -7099,7 +7197,7 @@ class ToolHandler {
         lines.push('---');
         if (mechanismClosed || (hasFlowPath && topIsStrong)) {
             lines.push('> **Mechanism explore complete — ANSWER NOW** from the Manager inventory + spine + digests above. '
-                + 'Do **not** call `homegraph_node`, Read, or Grep for symbols/files already shown. '
+                + 'Do **not** Read or Grep for symbols/files already shown. '
                 + 'Only one tighter `homegraph_explore` if a **named** Type essential to the answer is still missing.');
         }
         else if (softClose) {
@@ -8260,7 +8358,7 @@ class ToolHandler {
         }
         lines.push('---');
         lines.push('> **Compact local explore complete — ANSWER NOW.** ' +
-            'Do **not** Read/Grep/`homegraph_search`/`homegraph_explore`/`homegraph_node` for the same symbols.');
+            'Do **not** Read/Grep/`homegraph_search`/`homegraph_explore` for the same symbols.');
         lines.push('');
         return this.textResult(lines.join('\n'));
     }
@@ -9988,14 +10086,9 @@ class ToolHandler {
         const sessionPrior = (0, explore_session_state_1.viewForProject)((0, explore_session_state_1.readExploreSessionView)(args), projectRoot);
         const repeat = (0, explore_repeat_guard_1.decideExploreRepeat)(sessionPrior, query);
         if (!plan && this.shouldRefuseRepeatedEvidence(repeat, projectRoot)) {
-            const text = (0, explore_repeat_guard_1.formatExploreRepeatRefuse)(repeat, query);
-            return this.exploreResult(text, {
-                projectRoot,
-                query,
-                files: [],
-                sourceBytes: 0,
-                responseBytes: text.length,
-            });
+            // Do not record this refusal. A recorded return would restart the cooldown
+            // and a client retrying inside the window would never get through.
+            return this.textResult((0, explore_repeat_guard_1.formatExploreRepeatRefuse)(repeat, query));
         }
         // A planned step already tried fast paths once, before entering full explore.
         const compactLocal = plan ? null : this.tryFastInventoryExplore(cg, query, projectRoot)
@@ -10034,7 +10127,7 @@ class ToolHandler {
                 : locateAnchors.length === 1
                     ? `${locateAnchors[0]} ${query}`
                     : query;
-        const wantHints = !!(plan && (plan.source === 'llm' || plan.literalTexts?.length || plan.anchors?.length))
+        const wantHints = !!(plan && (plan.source === 'llm' || plan.literalTexts?.length || plan.anchors?.length || plan.requestContract))
             || exploreSourceScope !== 'all';
         const subgraph = await cg.findRelevantContext(contextQuery, {
             ...contextOpts,
@@ -10043,7 +10136,8 @@ class ToolHandler {
                         ...(plan?.anchors ?? []).filter((anchor) => !(plan?.bindings ?? []).some((node) => anchor === node.name || anchor === node.qualifiedName)),
                         ...locateAnchors,
                     ].slice(0, 16),
-                    searchTerms: plan?.searchTerms ?? [], literalTexts: plan?.literalTexts,
+                    searchTerms: plan?.searchTerms ?? [], literalTexts: [...new Set([...(plan?.literalTexts ?? []),
+                            ...((0, request_contract_1.accuracyTargetsEnabled)() && !plan?.bindings?.length ? (0, request_contract_1.contractLiteralTexts)(plan?.requestContract) : [])])].slice(0, 8),
                     sourceScope: exploreSourceScope,
                     nodeIds: (plan?.bindings ?? []).map((node) => node.id),
                 } } : {}),
@@ -10078,6 +10172,26 @@ class ToolHandler {
                 }
             }
         }
+        if (plan?.requestContract && ((0, request_contract_1.accuracyTargetsEnabled)() || (0, request_contract_1.accuracyCoverageEnabled)()) && plan.sourceScope !== 'sdk'
+            // Resource values need the existing resource + reference renderer; a bare
+            // declaration would silently drop the value-to-key witness.
+            && !subgraph.literalEvidence?.hits.some(hit => hit.kind === 'resource_reference')) {
+            // One existing retrieval pass; raw literal hits affect candidate order only.
+            // Actual target evidence is checked against hash-verified source in the packer.
+            const hits = subgraph.literalEvidence?.hits ?? [];
+            const fileHits = new Map();
+            for (const hit of hits) {
+                const labels = fileHits.get(hit.filePath) ?? new Set();
+                labels.add(hit.literal);
+                fileHits.set(hit.filePath, labels);
+            }
+            const candidates = [...subgraph.nodes.values()];
+            if ((0, request_contract_1.accuracyTargetsEnabled)())
+                candidates.sort((a, b) => (fileHits.get(b.filePath)?.size ?? 0) - (fileHits.get(a.filePath)?.size ?? 0));
+            const packed = this.tryArktsEvidenceExplore(cg, query, projectRoot, candidates, new Set(plan.bindings?.length ? plan.bindings.map(b => b.id) : subgraph.roots), args._hgEvidenceMaxChars, maxFiles, plan);
+            if (packed)
+                return packed;
+        }
         const literalSource = this.renderLiteralSource(cg, subgraph);
         if (subgraph.nodes.size === 0) {
             // Spec 0044 §9: empty exact evidence → Miss (paths only), not a source dump.
@@ -11166,9 +11280,9 @@ class ToolHandler {
         lines.push(exploreLocatorDigestEnabled()
             ? '> Spine / top-hit digests — treat as already Read. '
                 + 'Answer from Flow + Anchors + digests when you can; ONE narrow Grep for residual unindexed wiring. '
-                + 'Do not re-dump these files via Read/`homegraph_node`.'
+                + 'Do not re-dump these files via Read.'
             : '> Line-numbered source — treat as already Read. Answer from Flow + Source below when you can; ' +
-                'do not re-read/grep these files, and do not fan out `homegraph_node` / search for symbols already shown. ' +
+                'do not re-read/grep these files, and do not fan out search for symbols already shown. ' +
                 'Another `homegraph_explore` with tighter names only if a needed symbol is missing.');
         lines.push('');
         for (const [filePath, group] of filesToRender) {
@@ -11887,16 +12001,15 @@ class ToolHandler {
         }
         else if (anyFileTrimmed) {
             lines.push('');
-            lines.push(`> Some file sections were trimmed for size. For a specific symbol you still need, run another \`homegraph_explore\` (or \`homegraph_node\`) with its exact name — line-numbered source, cheaper and more complete than Read.`);
+            lines.push(`> Some file sections were trimmed for size. For a specific symbol you still need, run another \`homegraph_explore\` with its exact name — line-numbered source, cheaper and more complete than Read.`);
         }
         // Add explore budget note based on project size
         if (budget.includeBudgetNote) {
             try {
                 const stats = cg.getStats();
-                const callBudget = getExploreBudget(stats.fileCount);
                 lines.push('');
-                lines.push(`> **Usually one explore is enough** (budget ≤${callBudget} for ${stats.fileCount.toLocaleString()} files). ` +
-                    'Answer from Flow + Source above. Extra explore/`homegraph_node`/Read for the **same** symbols multiplies tokens — ' +
+                lines.push(`> **Usually one explore is enough** (wait ${(0, explore_repeat_guard_1.exploreCooldownSeconds)()}s after this result before another \`homegraph_explore\`; ${stats.fileCount.toLocaleString()} files). ` +
+                    'Answer from Flow + Source above. Extra explore/Read for the **same** symbols multiplies tokens — ' +
                     'only call again for a missing **named** symbol.');
             }
             catch {
@@ -11974,7 +12087,7 @@ class ToolHandler {
         if (!finalText.includes('**Partial result**') && !finalText.includes('> **Explore complete**')) {
             finalText +=
                 '\n\n> **Explore complete — ANSWER NOW.** Flow + Source above are authoritative for this query. ' +
-                    'Do **not** grep/read/`homegraph_node`/`homegraph_search` for the same symbols or files (multiplies tokens). ' +
+                    'Do **not** grep/read/`homegraph_search` for the same symbols or files (multiplies tokens). ' +
                     'Only call one tighter `homegraph_explore` if a named symbol essential to the answer is missing.';
         }
         // Curated header (#1046): substitute the sentinel with the count of files
@@ -12047,7 +12160,10 @@ class ToolHandler {
         const nodes = [];
         const seen = new Set();
         let chars = 0;
-        for (const hit of subgraph.literalEvidence?.hits ?? []) {
+        // Preserve value-to-key provenance when a plain label in the same file
+        // would otherwise consume its single source-witness slot first.
+        const literalHits = [...(subgraph.literalEvidence?.hits ?? [])].sort((a, b) => Number(!!b.resource) - Number(!!a.resource));
+        for (const hit of literalHits) {
             if (files.length >= 2 || seen.has(hit.filePath))
                 continue;
             const absolute = (0, utils_1.validatePathWithinRoot)(cg.getProjectRoot(), hit.filePath);