homegraph 1.6.0 → 1.6.2

package/dist/installer/targets/types.d.ts

@@ -17,7 +17,7 @@ export type Location = 'global' | 'local';
  * lookup. New targets add a value here when they're added to the
  * registry. Keep these short and lowercase.
  */
-export type TargetId = 'claude' | 'cursor' | 'codex' | 'opencode' | 'deveco' | 'codebuddy' | 'hermes' | 'gemini' | 'antigravity' | 'kiro';
+export type TargetId = 'claude' | 'cursor' | 'codex' | 'opencode' | 'deveco' | 'codebuddy' | 'hermes' | 'gemini' | 'antigravity' | 'kiro' | 'icode';
 /**
  * Result of `target.detect(location)`.
  *

package/dist/mcp/arkts-evidence-packs.d.ts

@@ -1,3 +1,6 @@
+import { type SdkModule } from './implementation-context';
+import { type RequestContract } from '../search/request-contract';
+import { type RequestEvidence, type ControlEvidence } from './request-evidence';
 import type HomeGraph from '../index';
 import type { Edge, Node } from '../types';
 import type { ExploreEmission } from './explore-session-state';
@@ -22,6 +25,15 @@ interface EvidencePack {
     sources: string[];
     priority: number;
     gaps: EvidenceGap[];
+    context?: {
+        label: string;
+        notes: string[];
+        sdk?: {
+            module: string;
+            version: string;
+            nodes: Node[];
+        };
+    };
     relation?: RelationEvidence;
     path?: {
         id: string;
@@ -36,6 +48,9 @@ export interface ArktsEvidenceResult {
         version: 1 | 2;
         scope: 'bounded_static_evidence';
         status: 'complete' | 'partial' | 'empty';
+        requestEvidence?: RequestEvidence;
+        controls?: ControlEvidence[];
+        implementationContext?: Array<NonNullable<EvidencePack['context']>>;
         selectedPacks: string[];
         gaps: EvidenceGap[];
         relations: NonNullable<EvidencePack['relation']>[];
@@ -62,6 +77,8 @@ export declare function buildArktsEvidencePacks(graph: Pick<HomeGraph, 'getNode'
     maxChars: number;
     maxFiles?: number;
     pathSearch?: EvidencePathSearch;
+    requestContract?: RequestContract;
+    sdkModule?: (module: string) => SdkModule | undefined;
 }): ArktsEvidenceResult | null;
 export {};
 //# sourceMappingURL=arkts-evidence-packs.d.ts.map

package/dist/mcp/arkts-evidence-packs.js

@@ -1,6 +1,44 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildArktsEvidencePacks = buildArktsEvidencePacks;
+const arkts_1 = require("../extraction/languages/arkts");
+const implementation_context_1 = require("./implementation-context");
+const path = __importStar(require("node:path"));
+const request_contract_1 = require("../search/request-contract");
+const request_evidence_1 = require("./request-evidence");
 const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
 const utils_1 = require("../utils");
@@ -8,7 +46,7 @@ const evidence_rendering_1 = require("./evidence-rendering");
 const explore_dedup_1 = require("./explore-dedup");
 const evidence_paths_1 = require("../graph/evidence-paths");
 const LIMITS = { nodes: 36, expand: 12, edges: 48, files: 8, fileBytes: 512 * 1024, bytes: 2 * 1024 * 1024 };
-const DECLARATIONS = new Set(['class', 'struct', 'component', 'interface', 'method', 'function', 'property', 'field', 'constant', 'variable', 'enum']);
+const BASE_DECLARATIONS = new Set(['class', 'struct', 'component', 'interface', 'method', 'function', 'property', 'field', 'constant', 'variable', 'enum']);
 const CONTAINERS = new Set(['class', 'struct', 'component', 'interface', 'enum']);
 const RELATIONS = new Set(['calls', 'references', 'extends', 'implements', 'instantiates']);
 const inline = (s) => s.replace(/[`\r\n]/g, ' ');
@@ -22,16 +60,32 @@ const artifact = (n) => n.filePath.includes('@dummy') || n.name.startsWith('@dum
     || (n.name === 'constructor' && n.startLine === 1 && n.endLine === 1);
 /** Consume already-located nodes. No text search, new planner call or recursive retrieval. */
 function buildArktsEvidencePacks(graph, options) {
+    const contextEnabled = (0, implementation_context_1.implementationContextEnabled)();
+    const DECLARATIONS = contextEnabled ? new Set([...BASE_DECLARATIONS, 'type_alias', 'import', 'export', 'route', 'file']) : BASE_DECLARATIONS;
     if (!options.nodes.some(n => local(n) && /\.ets$/i.test(n.filePath) && DECLARATIONS.has(n.kind)))
         return null;
     const search = options.pathSearch;
+    const targetChecks = (0, request_contract_1.accuracyTargetsEnabled)();
+    const behaviorChecks = (0, request_contract_1.accuracyCoverageEnabled)();
+    const inspector = options.requestContract && (targetChecks || behaviorChecks)
+        ? (0, request_evidence_1.createRequestEvidenceInspector)(options.requestContract) : undefined;
+    const requestSources = new Map();
+    const requestUnit = (s) => {
+        let unit = requestSources.get(s);
+        if (!unit) {
+            unit = { filePath: s.node.filePath, start: s.start, source: s.source };
+            requestSources.set(s, unit);
+        }
+        return unit;
+    };
     const requiredIds = search ? new Set([...search.goal.anchorIds, ...search.paths.flatMap(p => p.nodeIds)]) : options.focusIds;
     const inputNodes = search && requiredIds.size ? [...requiredIds].flatMap(id => { const n = graph.getNode(id); return n ? [n] : []; }) : options.nodes;
     const all = (0, evidence_rendering_1.canonicalSourceDeclarations)(inputNodes.filter(n => DECLARATIONS.has(n.kind) && local(n) && !artifact(n)));
     if (!all.length)
         return null;
+    const inputOrder = new Map(all.map((node, index) => [node.id, index]));
     const candidates = all.sort((a, b) => Number(requiredIds.has(b.id)) - Number(requiredIds.has(a.id))
-        || a.filePath.localeCompare(b.filePath) || a.startLine - b.startLine).slice(0, LIMITS.nodes);
+        || (inspector && targetChecks ? inputOrder.get(a.id) - inputOrder.get(b.id) : a.filePath.localeCompare(b.filePath) || a.startLine - b.startLine)).slice(0, LIMITS.nodes);
     const focus = candidates.filter(n => requiredIds.has(n.id));
     // A named owning type provides scope for its named members, not another
     // callable endpoint. Do not invent a missing Type→method call obligation.
@@ -46,11 +100,11 @@ function buildArktsEvidencePacks(graph, options) {
     let bytesRead = 0;
     const root = (0, node_fs_1.realpathSync)(options.projectRoot);
     const maxFiles = Math.max(1, Math.min(LIMITS.files, options.maxFiles ?? LIMITS.files));
-    const readSource = (node) => {
+    const readSource = (node, snapshot = false) => {
         const previous = nodeSources.get(node.id);
         if (previous)
             return previous;
-        if (!local(node) || artifact(node) || !DECLARATIONS.has(node.kind)) {
+        if ((!local(node) && !(contextEnabled && (snapshot || node.kind === 'route' || (!node.filePath.startsWith('ohos-sdk:') && /\.d\.(?:ts|ets)$/.test(node.filePath))))) || artifact(node) || !DECLARATIONS.has(node.kind)) {
             const failure = { gap: { target: label(node), reason: 'unavailable', nextAnchor: location(node) } };
             nodeSources.set(node.id, failure);
             return failure;
@@ -90,7 +144,7 @@ function buildArktsEvidencePacks(graph, options) {
                         const content = buffer.subarray(0, bytes).toString('utf8');
                         const indexed = graph.getFile(node.filePath);
                         // Hash equality, not mtime: edits can retain timestamps and invalidate ranges.
-                        if (bytes !== size || !indexed || indexed.contentHash !== (0, node_crypto_1.createHash)('sha256').update(content).digest('hex'))
+                        if (bytes !== size || (!snapshot && (!indexed || indexed.contentHash !== (0, node_crypto_1.createHash)('sha256').update(content).digest('hex'))))
                             file.reason = 'stale';
                         else
                             file = { content, lines: content.split('\n'), fingerprint: (0, explore_dedup_1.fileFingerprint)(content) };
@@ -102,6 +156,14 @@ function buildArktsEvidencePacks(graph, options) {
             }
             fileCache.set(node.filePath, file);
         }
+        if ((snapshot || node.kind === 'file') && file.lines)
+            node = { ...node, endLine: file.lines.length };
+        if (node.kind === 'import' && file.lines) {
+            const head = file.lines.slice(node.startLine - 1, node.startLine + 20).join('\n');
+            const importText = head.match(/^\s*import\s+[\s\S]*?\bfrom\s*['"][^'"\r\n]+['"][^\S\r\n]*;?/);
+            if (importText)
+                node = { ...node, endLine: node.startLine + importText[0].split('\n').length - 1 };
+        }
         const reason = file.reason ?? (!Number.isInteger(node.startLine) || !Number.isInteger(node.endLine)
             || node.startLine < 1 || node.endLine < node.startLine || node.endLine > file.lines.length
             || !file.lines.slice(node.startLine - 1, node.endLine).join('\n').trim() ? 'invalid_range' : undefined);
@@ -117,13 +179,13 @@ function buildArktsEvidencePacks(graph, options) {
         const id = `${node.filePath}:${start}-${node.endLine}`;
         if (!sources.has(id))
             sources.set(id, { id, node, start, end: node.endLine,
-                source: file.lines.slice(start - 1, node.endLine).join('\n'), fingerprint: file.fingerprint });
+                source: file.lines.slice(start - 1, node.endLine).join('\n'), fingerprint: file.fingerprint, ...(snapshot ? { snapshot: true } : {}) });
         const result = { id };
         nodeSources.set(node.id, result);
         return result;
     };
     const dependencies = (nodes) => {
-        const resolved = nodes.map(readSource);
+        const resolved = nodes.map(n => readSource(n));
         return { sources: [...new Set(resolved.flatMap(s => s.id ? [s.id] : []))],
             gaps: resolved.flatMap(s => s.gap ? [s.gap] : []) };
     };
@@ -134,6 +196,104 @@ function buildArktsEvidencePacks(graph, options) {
     if (all.length > candidates.length)
         globalGaps.push({ target: `${all.length - candidates.length} additional candidates`,
             reason: 'scope_limit', nextAnchor: location(all[candidates.length]) });
+    const configNode = (file) => ({ id: `context-config:${file}`, kind: 'constant', name: file, qualifiedName: file,
+        filePath: file, startLine: 1, endLine: 1, startColumn: 0, endColumn: 0, updatedAt: 0, language: 'yaml' });
+    const manifestCache = new Map();
+    const nearestManifest = (file) => {
+        if (manifestCache.has(file))
+            return manifestCache.get(file);
+        let dir = path.posix.dirname(file.replace(/\\/g, '/'));
+        let found;
+        for (let depth = 0; depth < 12; depth++) {
+            const manifest = path.posix.join(dir, 'oh-package.json5');
+            const absolute = (0, utils_1.validatePathWithinRoot)(root, manifest);
+            try {
+                if (absolute && (0, node_fs_1.statSync)(absolute).isFile()) {
+                    found = configNode(manifest);
+                    break;
+                }
+            }
+            catch { /* absent */ }
+            if (dir === '.')
+                break;
+            dir = path.posix.dirname(dir);
+        }
+        manifestCache.set(file, found);
+        return found;
+    };
+    const configValue = (node) => {
+        const r = readSource(node, true);
+        if (!r.id)
+            return undefined;
+        try {
+            const value = (0, arkts_1.parseJson5Minimal)(sources.get(r.id).source);
+            return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const moduleBinding = (importer, module) => {
+        const manifest = nearestManifest(importer);
+        if (!manifest)
+            return undefined;
+        const config = configValue(manifest);
+        const deps = config?.dependencies;
+        if (!deps || typeof deps !== 'object' || Array.isArray(deps))
+            return undefined;
+        const dep = deps[module];
+        if (typeof dep !== 'string' || !/^file:\.{1,2}\//.test(dep))
+            return undefined;
+        const depRoot = path.posix.normalize(path.posix.join(path.posix.dirname(manifest.filePath), dep.slice(5)));
+        if (depRoot === '..' || depRoot.startsWith('../') || path.posix.isAbsolute(depRoot))
+            return undefined;
+        const targetManifest = configNode(path.posix.join(depRoot, 'oh-package.json5'));
+        const target = configValue(targetManifest);
+        if (!target)
+            return undefined;
+        const entry = typeof target.main === 'string' ? path.posix.join(depRoot, target.main) : depRoot;
+        const relativePath = './' + path.posix.relative(path.posix.dirname(importer), entry);
+        return { relativePath, witnesses: [manifest, targetManifest] };
+    };
+    const contextGroups = contextEnabled ? (0, implementation_context_1.collectImplementationContext)(graph, focus.length ? focus : candidates, node => { const r = readSource(node); return r.id ? sources.get(r.id)?.source : undefined; }, options.sdkModule, moduleBinding) : [];
+    for (const group of contextGroups) {
+        const deps = dependencies(group.nodes);
+        packs.push({ id: group.id, label: group.label, priority: 130, ...deps,
+            context: { label: group.label, notes: [...group.notes, ...group.missing.map(m => `Unresolved: ${m}`)], ...(group.sdk ? { sdk: group.sdk } : {}) } });
+        for (const missing of group.missing)
+            globalGaps.push({ target: missing, reason: 'unindexed_connection', nextAnchor: missing });
+    }
+    // Only ancestor manifests of the located code; no workspace traversal or credential files.
+    const configs = new Set();
+    for (const node of contextEnabled && contextGroups.some(g => g.id.startsWith('impl-import:')) ? (focus.length ? focus : candidates).slice(0, 3) : []) {
+        let dir = path.posix.dirname(node.filePath.replace(/\\/g, '/'));
+        for (let depth = 0; depth < 12; depth++) {
+            const manifest = path.posix.join(dir, 'oh-package.json5');
+            const absolute = (0, utils_1.validatePathWithinRoot)(root, manifest);
+            try {
+                if (absolute && (0, node_fs_1.statSync)(absolute).isFile()) {
+                    configs.add(manifest);
+                    break;
+                }
+            }
+            catch { /* missing ancestor manifest */ }
+            if (dir === '.')
+                break;
+            dir = path.posix.dirname(dir);
+        }
+    }
+    if (configs.size)
+        configs.add('build-profile.json5');
+    for (const config of configs) {
+        const node = { id: `context-config:${config}`, kind: 'constant', name: config, qualifiedName: config,
+            filePath: config, startLine: 1, endLine: 1, startColumn: 0, endColumn: 0, updatedAt: Date.now(), language: 'yaml' };
+        const dep = readSource(node, true);
+        if (dep.id)
+            packs.push({ id: node.id, label: `module/version configuration ${config}`, priority: 125, sources: [dep.id], gaps: [],
+                context: { label: `module/version configuration ${config}`, notes: ['Current configuration snapshot; declared dependencies do not prove installation or export availability.'] } });
+        else if (dep.gap && dep.gap.reason !== 'unavailable')
+            globalGaps.push(dep.gap);
+    }
     const candidateIds = new Set(candidates.map(n => n.id));
     const edges = [];
     const edgeKeys = new Set();
@@ -158,6 +318,16 @@ function buildArktsEvidencePacks(graph, options) {
             edges.push(edge);
         }
     }
+    for (const group of contextGroups)
+        for (const edge of group.edges) {
+            if (edge.kind === 'imports')
+                continue;
+            const key = (0, evidence_paths_1.evidenceEdgeKey)(edge);
+            if (!edgeKeys.has(key)) {
+                edgeKeys.add(key);
+                edges.push(edge);
+            }
+        }
     if (search) {
         const fallbackNeighbors = search.missing.length || search.goal.anchorIds.length < 2 ? search.neighbors : [];
         for (const edge of [...search.paths.flatMap(p => p.edges), ...fallbackNeighbors]) {
@@ -194,7 +364,7 @@ function buildArktsEvidencePacks(graph, options) {
     for (const [i, edge] of edges.entries()) {
         const from = graph.getNode(edge.source);
         const to = graph.getNode(edge.target);
-        if (!from || !to || !local(from) || !local(to)) {
+        if (!from || !to || (!local(from) && from.kind !== 'route') || (!local(to) && to.kind !== 'route')) {
             globalGaps.push({ target: `${from ? label(from) : edge.source} ${edge.kind} ${to ? label(to) : edge.target}`,
                 reason: 'unavailable', nextAnchor: from ? location(from) : edge.source });
             continue;
@@ -267,6 +437,19 @@ function buildArktsEvidencePacks(graph, options) {
             globalGaps.push({ target: `connecting path in the bounded graph slice: ${label(relationFocus[0])} → ${label(disconnected[0])}`,
                 reason: 'unindexed_connection', nextAnchor: location(disconnected[0]) });
     }
+    // Rank already-read, hash-verified declarations by joint targets in the same file.
+    // Never discard a dependent helper merely because it has no UI label.
+    if (inspector && targetChecks) {
+        const byFile = new Map();
+        for (const unit of sources.values()) {
+            const list = byFile.get(unit.node.filePath) ?? [];
+            list.push(requestUnit(unit));
+            byFile.set(unit.node.filePath, list);
+        }
+        const scores = new Map([...byFile].map(([file, units]) => [file, inspector.score(units)]));
+        for (const pack of packs)
+            pack.priority += 30 * Math.max(0, ...pack.sources.map(id => scores.get(sources.get(id).node.filePath) ?? 0));
+    }
     const selected = [];
     const rejectedGap = (p) => p.gaps.length ? p.gaps : [{ target: p.label, reason: 'budget',
             nextAnchor: sources.get(p.sources[0] ?? '') ? location(sources.get(p.sources[0]).node) : p.label }];
@@ -281,6 +464,12 @@ function buildArktsEvidencePacks(graph, options) {
         return units.filter(s => !units.some(other => other.id !== s.id && other.node.filePath === s.node.filePath
             && other.start <= s.start && other.end >= s.end)).sort((a, b) => a.node.filePath.localeCompare(b.node.filePath) || a.start - b.start);
     };
+    const controlCache = new Map();
+    const controlsFor = (chosen) => unitsFor(chosen).flatMap(unit => {
+        if (!controlCache.has(unit))
+            controlCache.set(unit, (0, request_evidence_1.inspectControlEvidence)([requestUnit(unit)]));
+        return controlCache.get(unit);
+    }).slice(0, 8);
     const relationsFor = (chosen) => [...new Map(chosen.flatMap(p => p.path?.relations ?? (p.relation ? [p.relation] : []))
             .map(r => [JSON.stringify(r), r])).values()];
     const stopFor = (chosen) => search?.stopReason === 'supported'
@@ -291,6 +480,16 @@ function buildArktsEvidencePacks(graph, options) {
             'Complete declarations preserve internal branches. Enclosing callers and runtime order/value flow are not proven. Retrieval is not task completion.'];
         if (search)
             lines.push(`Path goal: ${search.goal.kind}; search direction: ${search.goal.direction}; stop: ${stopFor(chosen)}. Static paths do not prove runtime behavior.`);
+        if (inspector)
+            lines.push(...(0, request_evidence_1.renderRequestEvidence)(inspector.inspect(unitsFor(chosen).map(requestUnit)), targetChecks, behaviorChecks));
+        if ((0, implementation_context_1.controlEvidenceEnabled)())
+            lines.push(...(0, request_evidence_1.renderControlEvidence)(controlsFor(chosen)));
+        for (const pack of chosen.filter(p => p.context)) {
+            lines.push(`**Implementation context: ${inline(pack.context.label)}**`, ...pack.context.notes.map(n => `- ${inline(n)}`));
+            const sdk = pack.context.sdk;
+            if (sdk)
+                lines.push(`Indexed SDK signatures for ${inline(sdk.module)}; database version ${inline(sdk.version)}. Not source bodies or device validation.`, ...sdk.nodes.map(n => `- ${inline(n.filePath)}:${n.startLine} ${inline(n.signature || n.name)}${n.docstring ? ` — ${inline(n.docstring).slice(0, 500)}${n.docstring.length > 500 ? ' [documentation excerpt; remaining constraints not shown]' : ''}` : ''}`));
+        }
         const chosenPaths = chosen.filter(p => p.path);
         if (chosenPaths.length)
             lines.push('**Directed paths (all source dependencies provided)**', ...chosenPaths.map(p => `- ${inline(p.label)}`));
@@ -304,7 +503,7 @@ function buildArktsEvidencePacks(graph, options) {
         for (const unit of unitsFor(chosen)) {
             // Fence longer than any source backtick run: source-like guidance cannot escape.
             const fence = '`'.repeat(Math.max(3, ...Array.from(unit.source.matchAll(/`+/g), m => m[0].length + 1)));
-            lines.push(`### ${inline(unit.node.filePath)}:${unit.start}-${unit.end} — complete declaration; file-fingerprint=${unit.fingerprint}`, fence + unit.node.language, unit.source.split('\n').map((line, i) => `${unit.start + i}\t${line}`).join('\n'), fence);
+            lines.push(`### ${inline(unit.node.filePath)}:${unit.start}-${unit.end} — ${unit.snapshot ? 'current configuration snapshot' : unit.node.kind === 'file' ? 'complete indexed file' : 'complete declaration'}; file-fingerprint=${unit.fingerprint}`, fence + unit.node.language, unit.source.split('\n').map((line, i) => `${unit.start + i}\t${line}`).join('\n'), fence);
         }
         if (gaps.length) {
             lines.push('**Gaps — inspect only the missing evidence needed for the task**', ...gaps.slice(0, 6).map(g => `- ${g.reason}: ${inline(g.target)}. Next anchor: ${inline(g.nextAnchor)}.`));
@@ -341,11 +540,20 @@ function buildArktsEvidencePacks(graph, options) {
     const locatedNodes = candidates.filter(n => units.some(s => s.node.filePath === n.filePath && s.start <= n.startLine && s.end >= n.endLine))
         .map(n => ({ id: n.id, name: n.name, qualifiedName: n.qualifiedName, filePath: n.filePath, startLine: n.startLine }));
     const status = !units.length ? 'empty' : gaps.length ? 'partial' : 'complete';
+    const checkedRequest = inspector?.inspect(units.map(requestUnit));
+    const requestEvidence = checkedRequest ? { ...checkedRequest, targets: targetChecks ? checkedRequest.targets : [],
+        behaviors: behaviorChecks ? checkedRequest.behaviors : [] } : undefined;
     return { text, emission: { projectRoot: options.projectRoot, query: options.query, files,
             sourceBytes: files.reduce((sum, f) => sum + f.bytes, 0), responseBytes: text.length, locatedNodes,
             evidenceStatus: status, partial: status !== 'complete', coveredObligations: selected.map(p => p.label),
             uncoveredObligations: gaps.map(g => `${g.reason}: ${g.target}`), nextAnchor: gaps[0]?.nextAnchor },
-        metadata: { version: search ? 2 : 1, scope: 'bounded_static_evidence', status, selectedPacks: selected.map(p => p.id), gaps,
+        metadata: { ...((0, implementation_context_1.controlEvidenceEnabled)() ? { controls: controlsFor(selected) } : {}),
+            ...(contextEnabled ? { implementationContext: selected.flatMap(p => p.context ? [{ ...p.context,
+                        ...(p.context.sdk ? { sdk: { ...p.context.sdk, nodes: p.context.sdk.nodes.map(n => ({
+                                    id: n.id, name: n.name, qualifiedName: n.qualifiedName, kind: n.kind, filePath: n.filePath,
+                                    startLine: n.startLine, endLine: n.endLine, startColumn: n.startColumn, endColumn: n.endColumn,
+                                    language: n.language, updatedAt: n.updatedAt, signature: n.signature,
+                                })) } } : {}) }] : []) } : {}), ...(requestEvidence ? { requestEvidence } : {}), version: search ? 2 : 1, scope: 'bounded_static_evidence', status, selectedPacks: selected.map(p => p.id), gaps,
             relations: relationsFor(selected), ...(search ? { pathSearch: { goal: search.goal, stopReason: stopFor(selected),
                     limitsHit: search.limitsHit, stats: search.stats, paths: search.paths.map(p => ({ id: p.id, nodeIds: p.nodeIds, cost: p.cost,
                         evidence: selected.some(c => c.path?.id === p.id) ? 'provided' : 'partial' })) } } : {}) } };

package/dist/mcp/evidence-audit.d.ts

@@ -0,0 +1,3 @@
+/** Opt-in local evidence only, never an answer cache. Logging cannot break retrieval. */
+export declare function recordEvidencePack(projectRoot: string, input: unknown, output: unknown): 'written' | 'disabled' | 'limit' | 'unavailable';
+//# sourceMappingURL=evidence-audit.d.ts.map

package/dist/mcp/evidence-audit.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordEvidencePack = recordEvidencePack;
+const node_fs_1 = require("node:fs");
+const node_crypto_1 = require("node:crypto");
+const utils_1 = require("../utils");
+/** Opt-in local evidence only, never an answer cache. Logging cannot break retrieval. */
+function recordEvidencePack(projectRoot, input, output) {
+    if (process.env.HOMEGRAPH_ARKTS_EVIDENCE_LOG !== '1')
+        return 'disabled';
+    let fd;
+    try {
+        const target = (0, utils_1.validatePathWithinRoot)(projectRoot, '.homegraph/evidence-packs.jsonl');
+        if (!target)
+            return 'unavailable';
+        const record = Buffer.from(JSON.stringify({ id: (0, node_crypto_1.randomUUID)(), time: new Date().toISOString(),
+            stage: 'arkts_pack_before_host_wrapping', version: 1, input, output }) + '\n');
+        fd = (0, node_fs_1.openSync)(target, node_fs_1.constants.O_WRONLY | node_fs_1.constants.O_CREAT | node_fs_1.constants.O_APPEND | node_fs_1.constants.O_NONBLOCK | (node_fs_1.constants.O_NOFOLLOW ?? 0), 0o600);
+        if (!(0, node_fs_1.fstatSync)(fd).isFile())
+            return 'unavailable';
+        if ((0, node_fs_1.fstatSync)(fd).size + record.length > 16 * 1024 * 1024)
+            return 'limit';
+        let at = 0;
+        while (at < record.length) {
+            const written = (0, node_fs_1.writeSync)(fd, record, at);
+            if (!written)
+                return 'unavailable';
+            at += written;
+        }
+        return 'written';
+    }
+    catch {
+        return 'unavailable';
+    }
+    finally {
+        if (fd !== undefined)
+            (0, node_fs_1.closeSync)(fd);
+    }
+}
+//# sourceMappingURL=evidence-audit.js.map

package/dist/mcp/evidence-rendering.js

@@ -52,7 +52,7 @@ function neutralRetrievalGuidance(text) {
         return line
             .replace(/\*{0,2}ANSWER NOW\*{0,2}/g, 'use the evidence shown')
             .replace(/Flow \+ Source above are authoritative for this query\./g, 'Source coverage is limited to the displayed ranges.')
-            .replace(/Do \*\*not\*\* grep\/read\/`homegraph_node`\/`homegraph_search`[^.]*\./gi, 'Inspect missing evidence as needed.')
+            .replace(/Do \*\*not\*\* grep\/read\/(?:`homegraph_node`\/)?`homegraph_search`[^.]*\./gi, 'Inspect missing evidence as needed.')
             .replace(/do\s+\*{0,2}not\*{0,2}\s+(?:re-)?(?:grep|read|glob)(?:\/[^.;]+)?[^.;]*[.;]/gi, 'Avoid duplicate reads of unchanged ranges;');
     }).join('\n');
 }

package/dist/mcp/explore-repeat-guard.d.ts

@@ -40,14 +40,28 @@ export declare function inferExplorePartialMeta(text: string): {
 };
 export interface ExploreRepeatDecision {
     refuse: boolean;
-    /** Matched prior call when refusing for overlap. */
+    /** Matched prior call when refusing for overlap or cooldown. */
     matched?: ExploreCallRecord;
-    reason: 'overlap' | 'call-budget' | 'hard-cap' | 'next-anchor' | 'ok';
+    reason: 'overlap' | 'call-budget' | 'cooldown' | 'next-anchor' | 'ok';
 }
+/**
+ * After `homegraph_explore` records a result (the response is about to be
+ * returned), refuse another explore on the same project until this elapses.
+ * There is no per-connection call ceiling — a later question on a long-lived
+ * MCP session must still be able to explore.
+ *
+ * Tool descriptions, initialize instructions, and explore footers must quote
+ * this same wait. `getExploreBudget` scales output size only.
+ */
+export declare const EXPLORE_COOLDOWN_MS = 10000;
+/** Whole seconds shown to agents. Matches {@link EXPLORE_COOLDOWN_MS}. */
+export declare function exploreCooldownSeconds(): number;
 /**
  * Whether this explore should short-refuse instead of re-running.
+ *
+ * `now` is injectable so tests can move past the cooldown without sleeping.
  */
-export declare function decideExploreRepeat(prior: ExploreProjectState | null | undefined, query: string): ExploreRepeatDecision;
+export declare function decideExploreRepeat(prior: ExploreProjectState | null | undefined, query: string, now?: number): ExploreRepeatDecision;
 /** Short success-shaped refuse when a repeat explore would waste tokens. */
 export declare function formatExploreRepeatRefuse(decision: ExploreRepeatDecision, query: string): string;
 export interface DepthToolFuseDecision {
@@ -98,8 +112,8 @@ export declare function formatMechanismSoftCloseFooter(next?: DomainRoleAnchorCa
 /** Honest Partial footer with a single Next anchor + ONE Grep. */
 export declare function formatMechanismPartialFooter(nextCaption: string): string;
 /**
- * Appended when a second counted Partial is emitted in the same session —
- * stop HomeGraph; do not take a third explore.
+ * Appended when another Partial is emitted after one earlier Partial in this
+ * session. The wait is the return cooldown, not a connection-long stop.
  */
 export declare function formatSecondPartialStopFooter(nextAnchor?: string): string;
 /**

package/dist/mcp/explore-repeat-guard.js

@@ -9,6 +9,7 @@
  * Shape-driven only — no product nouns.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXPLORE_COOLDOWN_MS = void 0;
 exports.exploreQueryTokens = exploreQueryTokens;
 exports.queryTokenJaccard = queryTokenJaccard;
 exports.queryTokenOverlapScore = queryTokenOverlapScore;
@@ -17,6 +18,7 @@ exports.novelAnchorsVsPriors = novelAnchorsVsPriors;
 exports.isTightExploreFollowUp = isTightExploreFollowUp;
 exports.extractNextAnchorFromText = extractNextAnchorFromText;
 exports.inferExplorePartialMeta = inferExplorePartialMeta;
+exports.exploreCooldownSeconds = exploreCooldownSeconds;
 exports.decideExploreRepeat = decideExploreRepeat;
 exports.formatExploreRepeatRefuse = formatExploreRepeatRefuse;
 exports.latestCountedExplore = latestCountedExplore;
@@ -159,10 +161,19 @@ function inferExplorePartialMeta(text) {
     };
 }
 /**
- * Absolute retrieval budget per session/project. Empty receipts count as
- * attempts too, so failed recovery cannot create an unbounded retry loop.
+ * After `homegraph_explore` records a result (the response is about to be
+ * returned), refuse another explore on the same project until this elapses.
+ * There is no per-connection call ceiling — a later question on a long-lived
+ * MCP session must still be able to explore.
+ *
+ * Tool descriptions, initialize instructions, and explore footers must quote
+ * this same wait. `getExploreBudget` scales output size only.
  */
-const MAX_EXPLORES = 2;
+exports.EXPLORE_COOLDOWN_MS = 10_000;
+/** Whole seconds shown to agents. Matches {@link EXPLORE_COOLDOWN_MS}. */
+function exploreCooldownSeconds() {
+    return Math.round(exports.EXPLORE_COOLDOWN_MS / 1000);
+}
 /**
  * After a counted Partial explore, allow this many depth tools
  * (`homegraph_node` / callers / callees) before refusing — stops Partial→node×N
@@ -172,20 +183,30 @@ const MAX_DEPTH_AFTER_PARTIAL = 1;
 function isCountedCall(call) {
     return call.evidenceStatus !== undefined || (call.responseBytes || 0) >= 400;
 }
+function latestReturnedCall(prior) {
+    for (let i = prior.calls.length - 1; i >= 0; i--) {
+        const call = prior.calls[i];
+        if (call && typeof call.returnedAt === 'number' && Number.isFinite(call.returnedAt))
+            return call;
+    }
+    return undefined;
+}
 /**
  * Whether this explore should short-refuse instead of re-running.
+ *
+ * `now` is injectable so tests can move past the cooldown without sleeping.
  */
-function decideExploreRepeat(prior, query) {
+function decideExploreRepeat(prior, query, now = Date.now()) {
     if (!prior || prior.calls.length === 0)
         return { refuse: false, reason: 'ok' };
     const counted = prior.calls.filter(isCountedCall);
     const last = counted[counted.length - 1];
-    // Keep the lifetime budget even if bounded state has evicted early receipts.
-    if (Math.max(prior.callCount, counted.length) >= MAX_EXPLORES) {
+    const returned = latestReturnedCall(prior);
+    if (returned && now - returned.returnedAt < exports.EXPLORE_COOLDOWN_MS) {
         return {
             refuse: true,
-            matched: last,
-            reason: 'hard-cap',
+            matched: returned,
+            reason: 'cooldown',
         };
     }
     // Missing or SDK-only evidence is not a successfully answered query. Permit
@@ -217,8 +238,8 @@ function formatExploreRepeatRefuse(decision, query) {
         : '';
     let why;
     switch (decision.reason) {
-        case 'hard-cap':
-            why = `This session reached its **${MAX_EXPLORES}** \`homegraph_explore\` retrieval attempts on this project, including incomplete attempts.`;
+        case 'cooldown':
+            why = `The previous \`homegraph_explore\` result was returned less than **${exploreCooldownSeconds()}** seconds ago. Wait, reuse that result, or inspect with Read/Grep, then call explore again.`;
             break;
         case 'next-anchor':
             why = `Prior explore was Partial and named a **Next anchor** — do not re-explore a paraphrase of "${priorQ}${priorQ.length >= 100 ? '…' : ''}".`;
@@ -415,8 +436,8 @@ function formatMechanismPartialFooter(nextCaption) {
         + 'Use targeted Read/Grep if the evidence remains missing; an inventory alone does not establish behavior.');
 }
 /**
- * Appended when a second counted Partial is emitted in the same session —
- * stop HomeGraph; do not take a third explore.
+ * Appended when another Partial is emitted after one earlier Partial in this
+ * session. The wait is the return cooldown, not a connection-long stop.
  */
 function formatSecondPartialStopFooter(nextAnchor) {
     const next = nextAnchor
@@ -425,7 +446,7 @@ function formatSecondPartialStopFooter(nextAnchor) {
     return [
         '',
         '---',
-        '> **Second Partial — explore retrieval budget reached.** Do not repeat `homegraph_explore`.'
+        `> **Second Partial.** Wait ${exploreCooldownSeconds()} seconds after this result before calling \`homegraph_explore\` again.`
             + next
             + ' Evidence remains incomplete. Inspect only missing source with targeted Read or narrow Grep, '
             + 'then continue the requested edits and validation. Reuse unchanged source already returned.',
@@ -473,7 +494,7 @@ function formatPartialExploreGuidance(opts) {
         `⚠️ **Partial result** — ${why}. This is NOT an error.`,
         'A targeted Read or **ONE narrow Grep** may recover missing evidence using names already in the question.',
         anchorLine,
-        'At most **one** focused `homegraph_node` or callers/callees recovery after Partial; reuse source already returned.',
+        'At most **one** focused callers/callees recovery after Partial; reuse source already returned.',
         'If a second explore is still Partial, its retrieval budget is exhausted. Inspect missing source directly and continue the requested work; do not infer task completion.',
     ].join('\n');
 }

package/dist/mcp/explore-session-state.d.ts

@@ -118,6 +118,11 @@ export interface ExploreEmission {
 export interface ExploreCallRecord extends ExploreEmission {
     /** 1-based call index within this session FOR THIS PROJECT. Survives eviction. */
     index: number;
+    /**
+     * Epoch ms when this result was recorded and about to be returned.
+     * The explore cooldown measures from here, not from when the request arrived.
+     */
+    returnedAt?: number;
 }
 /** Everything the session knows about one project. */
 export interface ExploreProjectState {

package/dist/mcp/explore-session-state.js

@@ -215,6 +215,7 @@ class ExploreSessionState {
         state.responseBytes += Math.max(0, emission.responseBytes || 0);
         const record = {
             index: state.callCount,
+            returnedAt: Date.now(),
             projectRoot: emission.projectRoot,
             query: typeof emission.query === 'string' ? emission.query : '',
             files: this.boundFiles(emission.files),