homegraph 1.5.10 → 1.6.1

package/dist/mcp/engine.js

@@ -44,7 +44,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MCPEngine = void 0;
+exports.parseDeferProbeMs = exports.isIndexableRoot = exports.MCPEngine = void 0;
 exports.parseFixedWindowEnv = parseFixedWindowEnv;
 exports.parseDebounceEnv = parseDebounceEnv;
 const os = __importStar(require("os"));
@@ -57,13 +57,28 @@ const memory_budget_1 = require("./memory-budget");
 const db_1 = require("../db");
 const graph_sources_1 = require("../graph-sources");
 const utils_1 = require("../utils");
+const runtime_log_1 = require("../runtime-log");
+const indexable_root_1 = require("./indexable-root");
 // Lazy-load the heavy HomeGraph chain (sqlite + query/graph/context layers) OFF
 // the MCP startup path. It's only needed once a tool actually opens a project —
 // not to answer initialize/tools-list — so deferring it lets `serve mcp` (and
 // the daemon it spawns) bind + register tools in ~Node-startup time instead of
 // ~800ms, closing the "No such tool available" cold-start race that made headless
-// agents flounder. require() is sync + cached on the CommonJS build.
-const loadHomeGraph = () => require('../index').default;
+// agents flounder. Prefer dynamic import (vitest + CJS); sync require remains for
+// the sync retry path after an async load has warmed the cache (or under dist/).
+let homeGraphCtor = null;
+const loadHomeGraph = async () => {
+    if (!homeGraphCtor) {
+        homeGraphCtor = (await Promise.resolve().then(() => __importStar(require('../index')))).default;
+    }
+    return homeGraphCtor;
+};
+const loadHomeGraphSync = () => {
+    if (homeGraphCtor)
+        return homeGraphCtor;
+    homeGraphCtor = require('../index').default;
+    return homeGraphCtor;
+};
 /**
  * Shared MCP engine. Thread-safe in the sense that multiple sessions can
  * call its methods concurrently — internally it serializes initialization
@@ -85,6 +100,13 @@ class MCPEngine {
     // Off-loop read-tool pool (daemon mode only). Created lazily once the default
     // project is open — workers each hold their own WAL read connection.
     queryPool = null;
+    /**
+     * Spec 0049: auto-init deferred because the root was empty. Probe until
+     * indexable, then run the normal create-DB path once.
+     */
+    deferredAutoInitRoot = null;
+    deferProbeTimer = null;
+    deferAutoInitPromise = null;
     constructor(opts = {}) {
         this.opts = { watch: opts.watch ?? true, queryPool: opts.queryPool ?? false, rootFloor: opts.rootFloor ?? null };
         this.toolHandler = new tools_1.ToolHandler(null);
@@ -132,10 +154,42 @@ class MCPEngine {
     getToolHandler() {
         return this.toolHandler;
     }
+    /**
+     * Spec 0047: true while auto-init / full symbol build is in flight.
+     * Used by the daemon idle timer — never idle-exit mid-build when clients=0.
+     * Does not include routine watch/sync increments.
+     */
+    isIndexBuildInProgress() {
+        if (!this.cg)
+            return false;
+        try {
+            const phase = this.cg.getBuildPhase();
+            return phase === 'building_fast' || phase === 'indexing';
+        }
+        catch {
+            return false;
+        }
+    }
     /** Whether the default project's HomeGraph is open. */
     hasDefaultHomeGraph() {
         return this.toolHandler.hasDefaultHomeGraph();
     }
+    /** Spec 0049: true while auto-init is waiting for an empty root to grow sources. */
+    isAutoInitDeferred() {
+        return this.deferredAutoInitRoot !== null && !this.toolHandler.hasDefaultHomeGraph();
+    }
+    /**
+     * Spec 0049: on tool call (or timer), re-check the deferred root and start
+     * the normal auto-init once it becomes indexable. Idempotent.
+     */
+    async kickDeferredAutoInit() {
+        if (this.closed || this.toolHandler.hasDefaultHomeGraph())
+            return false;
+        const root = this.deferredAutoInitRoot;
+        if (!root)
+            return false;
+        return this.tryAutoInit(root);
+    }
     /**
      * Walk up from `searchFrom` to find the nearest `.homegraph/` and open it.
      * Idempotent: concurrent callers share one in-flight init; subsequent
@@ -194,7 +248,7 @@ class MCPEngine {
                 catch { /* ignore */ }
                 this.cg = null;
             }
-            this.cg = loadHomeGraph().openSync(resolvedRoot, { sources: mode });
+            this.cg = loadHomeGraphSync().openSync(resolvedRoot, { sources: mode });
             this.projectPath = resolvedRoot;
             this.toolHandler.setDefaultHomeGraph(this.cg);
             this.startWatching();
@@ -213,6 +267,7 @@ class MCPEngine {
         if (this.closed)
             return;
         this.closed = true;
+        this.clearDeferProbe();
         // Detach + terminate the worker pool first so no tool call routes to a
         // worker mid-teardown; outstanding pool calls resolve with graceful guidance.
         this.toolHandler.setQueryPool(null);
@@ -252,7 +307,7 @@ class MCPEngine {
                 process.stderr.write(`[HomeGraph MCP] Graph sources=${mode} — skipping project/SDK open (tools return guidance).\n`);
                 return;
             }
-            this.cg = await loadHomeGraph().open(resolvedRoot, { sources: mode });
+            this.cg = await (await loadHomeGraph()).open(resolvedRoot, { sources: mode });
             this.toolHandler.setDefaultHomeGraph(this.cg);
             this.healBuildPhase(this.cg);
             this.startWatching();
@@ -282,11 +337,34 @@ class MCPEngine {
         // Race: another process finished init before we entered — open, don't bail
         // (Spec 0032). Returning false here left the session with no cg forever.
         if ((0, directory_1.isInitialized)(root)) {
+            this.clearDeferProbe();
             return this.openAfterAutoInitRace(root);
         }
+        // Spec 0049: empty workspace — do not create `.homegraph/` (blocks
+        // in-place `devecocli create`). Probe later / on tool kick.
+        if (!(0, indexable_root_1.isIndexableRoot)(root)) {
+            this.armDeferProbe(root);
+            process.stderr.write(`[HomeGraph MCP] Auto-init deferred — empty root at ${root} ` +
+                `(no build-profile.json5 / indexable sources yet)\n`);
+            (0, runtime_log_1.logLifecycle)('auto-init.deferred', { projectRoot: root });
+            this.projectPath = root;
+            return false;
+        }
+        if (this.deferAutoInitPromise) {
+            return this.deferAutoInitPromise;
+        }
+        this.deferAutoInitPromise = this.runAutoInitCreate(root).finally(() => {
+            this.deferAutoInitPromise = null;
+        });
+        return this.deferAutoInitPromise;
+    }
+    /** Spec 0049: create DB + fast map + background full (shared by first hit and kick). */
+    async runAutoInitCreate(root) {
+        this.clearDeferProbe();
         try {
             process.stderr.write(`[HomeGraph MCP] Auto-init at ${root}\n`);
-            const HomeGraph = loadHomeGraph();
+            (0, runtime_log_1.logLifecycle)('auto-init.start', { projectRoot: root });
+            const HomeGraph = await loadHomeGraph();
             // Create DB immediately so tools/open succeed; index in background.
             const cg = await HomeGraph.init(root, { index: false });
             // Pin empty state before returning so the first tool call cannot see `none`
@@ -312,6 +390,7 @@ class MCPEngine {
                 catch (err) {
                     const msg = err instanceof Error ? err.message : String(err);
                     process.stderr.write(`[HomeGraph MCP] Fast build failed: ${msg}\n`);
+                    (0, runtime_log_1.logLifecycleError)('auto-init.fail', { projectRoot: root, phase: 'fast', msg });
                 }
                 this.startBackgroundFullBuild(cg);
             })();
@@ -324,9 +403,51 @@ class MCPEngine {
             }
             const msg = err instanceof Error ? err.message : String(err);
             process.stderr.write(`[HomeGraph MCP] Auto-init failed: ${msg}\n`);
+            (0, runtime_log_1.logLifecycleError)('auto-init.fail', { projectRoot: root, msg });
+            // Keep probing so a later scaffold (or retry) can still land.
+            if (!(0, directory_1.isInitialized)(root)) {
+                this.armDeferProbe(root);
+            }
             return false;
         }
     }
+    /** Spec 0049: remember empty root and (optionally) poll until indexable. */
+    armDeferProbe(root) {
+        this.deferredAutoInitRoot = root;
+        if (this.deferProbeTimer)
+            return;
+        const ms = (0, indexable_root_1.parseDeferProbeMs)(process.env.HOMEGRAPH_DEFER_PROBE_MS);
+        if (ms <= 0)
+            return;
+        this.deferProbeTimer = setInterval(() => {
+            if (this.closed || this.toolHandler.hasDefaultHomeGraph()) {
+                this.clearDeferProbe();
+                return;
+            }
+            const target = this.deferredAutoInitRoot;
+            if (!target) {
+                this.clearDeferProbe();
+                return;
+            }
+            if (!(0, indexable_root_1.isIndexableRoot)(target))
+                return;
+            void this.tryAutoInit(target).then((ok) => {
+                if (ok)
+                    this.clearDeferProbe();
+            });
+        }, ms);
+        // Don't keep the process alive solely for the probe in direct mode.
+        if (typeof this.deferProbeTimer.unref === 'function') {
+            this.deferProbeTimer.unref();
+        }
+    }
+    clearDeferProbe() {
+        this.deferredAutoInitRoot = null;
+        if (this.deferProbeTimer) {
+            clearInterval(this.deferProbeTimer);
+            this.deferProbeTimer = null;
+        }
+    }
     /**
      * Open an index another process just created (Spec 0032 cold-start race).
      * Brief retries cover the window between mkdir and db file create.
@@ -342,7 +463,7 @@ class MCPEngine {
             }
             try {
                 process.stderr.write(`[HomeGraph MCP] Auto-init raced; opening existing index at ${root}\n`);
-                this.cg = await loadHomeGraph().open(root, { sources: mode });
+                this.cg = await (await loadHomeGraph()).open(root, { sources: mode });
                 this.projectPath = root;
                 this.toolHandler.setDefaultHomeGraph(this.cg);
                 this.healBuildPhase(this.cg);
@@ -400,6 +521,14 @@ class MCPEngine {
     startBackgroundFullBuild(cg) {
         cg.setBuildPhase('indexing');
         process.stderr.write('[HomeGraph MCP] Full build starting in-process (background)\n');
+        let projectRoot;
+        try {
+            projectRoot = cg.getProjectRoot();
+        }
+        catch {
+            projectRoot = this.projectPath ?? undefined;
+        }
+        (0, runtime_log_1.logLifecycle)('index.start', { projectRoot, via: 'auto-init' });
         void cg
             .indexAll()
             .then((result) => {
@@ -420,16 +549,20 @@ class MCPEngine {
                 cg.setBuildPhase('full');
                 process.stderr.write(`[HomeGraph MCP] Full build complete — files=${files || '?'} nodes=${nodes}` +
                     (ok ? '\n' : ' (soft-fail but symbols present)\n'));
+                (0, runtime_log_1.logLifecycle)('index.done', { projectRoot, files, nodes });
+                (0, runtime_log_1.logLifecycle)('auto-init.done', { projectRoot, files, nodes });
             }
             else {
                 cg.setBuildPhase('fast');
                 process.stderr.write('[HomeGraph MCP] Full build finished with no symbols — staying on fast map\n');
+                (0, runtime_log_1.logLifecycle)('index.done', { projectRoot, files: 0, nodes: 0, note: 'no-symbols' });
             }
             this.startWatchingAfterAutoInit();
         })
             .catch((err) => {
             const msg = err instanceof Error ? err.message : String(err);
             process.stderr.write(`[HomeGraph MCP] Full build failed: ${msg}\n`);
+            (0, runtime_log_1.logLifecycleError)('index.fail', { projectRoot, msg });
             try {
                 let nodes = 0;
                 try {
@@ -575,6 +708,9 @@ function parseFixedWindowEnv(raw) {
         return undefined;
     return n;
 }
+var indexable_root_2 = require("./indexable-root");
+Object.defineProperty(exports, "isIndexableRoot", { enumerable: true, get: function () { return indexable_root_2.isIndexableRoot; } });
+Object.defineProperty(exports, "parseDeferProbeMs", { enumerable: true, get: function () { return indexable_root_2.parseDeferProbeMs; } });
 /**
  * Parse and clamp the HOMEGRAPH_WATCH_DEBOUNCE_MS env override.
  *

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/implementation-context.d.ts

@@ -0,0 +1,35 @@
+import type { Edge, Node } from '../types';
+export declare const implementationContextEnabled: () => boolean;
+export declare const controlEvidenceEnabled: () => boolean;
+export interface ImplementationGraph {
+    getNode(id: string): Node | null | undefined;
+    getNodesInFile(file: string): Node[];
+    getOutgoingEdges(id: string): Edge[];
+    getIncomingEdges(id: string): Edge[];
+}
+export interface ImplementationGroup {
+    id: string;
+    label: string;
+    nodes: Node[];
+    edges: Edge[];
+    notes: string[];
+    missing: string[];
+    sdk?: {
+        module: string;
+        version: string;
+        nodes: Node[];
+    };
+}
+export interface SdkModule {
+    version: string;
+    nodes: Node[];
+}
+/** No fuzzy symbol lookup: only stored edges and the target file of an actual import.
+ * Source must be hash-verified by the caller before its relationships are expanded.
+ * Limits bound work independently of repository size; gaps survive budget selection.
+ */
+export declare function collectImplementationContext(graph: ImplementationGraph, seeds: Node[], source: (node: Node) => string | undefined, sdkModule?: (module: string) => SdkModule | undefined, moduleBinding?: (importer: string, module: string) => {
+    relativePath: string;
+    witnesses: Node[];
+} | undefined): ImplementationGroup[];
+//# sourceMappingURL=implementation-context.d.ts.map

package/dist/mcp/implementation-context.js

@@ -0,0 +1,232 @@
+"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.controlEvidenceEnabled = exports.implementationContextEnabled = void 0;
+exports.collectImplementationContext = collectImplementationContext;
+const evidence_paths_1 = require("../graph/evidence-paths");
+const request_evidence_1 = require("./request-evidence");
+const path = __importStar(require("node:path"));
+const implementationContextEnabled = () => process.env.HOMEGRAPH_ARKTS_IMPLEMENTATION_CONTEXT !== '0';
+exports.implementationContextEnabled = implementationContextEnabled;
+const controlEvidenceEnabled = () => process.env.HOMEGRAPH_ARKTS_CONTROL_EVIDENCE !== '0';
+exports.controlEvidenceEnabled = controlEvidenceEnabled;
+const DECLARATIONS = new Set(['class', 'struct', 'component', 'interface', 'function', 'method', 'field', 'property', 'type_alias', 'enum', 'variable', 'constant']);
+const TYPES = new Set(['type_of', 'returns', 'instantiates']);
+const at = (n) => `${n.filePath}:${n.startLine}`;
+const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const uses = (code, name) => /^[\w$]+$/.test(name) && new RegExp(`(?<![\\w$])${esc(name)}(?![\\w$])`).test(code);
+/** No fuzzy symbol lookup: only stored edges and the target file of an actual import.
+ * Source must be hash-verified by the caller before its relationships are expanded.
+ * Limits bound work independently of repository size; gaps survive budget selection.
+ */
+function collectImplementationContext(graph, seeds, source, sdkModule, moduleBinding) {
+    const groups = [];
+    const files = new Map();
+    const sdkCache = new Map();
+    const inFile = (file) => {
+        if (!files.has(file))
+            files.set(file, graph.getNodesInFile(file));
+        return files.get(file);
+    };
+    // Import edges may be absent for ArkAnalyzer type-only imports. Resolve the exact
+    // relative module path, including barrel exports, without searching other modules.
+    let moduleReads = 0;
+    const relativeDefinition = (importer, module, name, depth = 0) => {
+        if (!module.startsWith('.') || depth > 2 || moduleReads >= 12)
+            return [];
+        const base = path.posix.normalize(path.posix.join(path.posix.dirname(importer), module));
+        if (base === '..' || base.startsWith('../') || path.posix.isAbsolute(base))
+            return [];
+        const paths = /\.(?:ets|ts)$/.test(base) ? [base] : [base + '.ets', base + '.ts', `${base}/Index.ets`, `${base}/index.ets`, `${base}/index.ts`];
+        const available = paths.map(file => ({ file, nodes: inFile(file) })).filter(x => x.nodes.length);
+        if (available.length !== 1)
+            return [];
+        moduleReads++;
+        const { file, nodes } = available[0];
+        const matches = [...new Map(nodes.filter(n => DECLARATIONS.has(n.kind) && n.name === name)
+                .map(n => [`${n.filePath}:${n.startLine}:${n.name}`, n])).values()];
+        if (matches.length === 1) {
+            const body = source(matches[0]);
+            if (body && new RegExp(`\\bexport\\s+(?:declare\\s+)?(?:class|struct|interface|enum|type|function|const|let|var)\\s+${esc(name)}\\b`).test((0, request_evidence_1.lexEvidenceSource)(body).code))
+                return [[matches[0]]];
+        }
+        const fileNode = { ...nodes[0], id: `context-file:${file}`, name: file, qualifiedName: file, kind: 'file', startLine: 1, endLine: 1 };
+        const body = source(fileNode);
+        if (!body)
+            return [];
+        const out = [];
+        const exportCode = (0, request_evidence_1.lexEvidenceSource)(body);
+        if (!exportCode.valid)
+            return [];
+        for (const m of body.matchAll(/\bexport\s+(\*|\{[^}]+\})\s+from\s*['"]([^'"\r\n]+)['"]/g)) {
+            if (!exportCode.code.slice(m.index).startsWith('export'))
+                continue;
+            let original = name;
+            if (m[1] !== '*') {
+                const binding = m[1].slice(1, -1).split(',').map(x => x.trim().split(/\s+as\s+/))
+                    .find(parts => (parts[1] ?? parts[0]) === name);
+                if (!binding)
+                    continue;
+                original = binding[0];
+            }
+            for (const chain of relativeDefinition(file, m[2], original, depth + 1))
+                out.push([fileNode, ...chain]);
+        }
+        return out;
+    };
+    const queue = seeds.slice(0, 6).map(n => ({ node: n, depth: 0 }));
+    const visited = new Set();
+    const seenEdges = new Set();
+    const seenImports = new Set();
+    let reads = 0;
+    while (queue.length && visited.size < 24 && reads < 48 && groups.length < 24) {
+        const { node, depth } = queue.shift();
+        if (visited.has(node.id) || node.filePath.startsWith('ohos-sdk:'))
+            continue;
+        visited.add(node.id);
+        const body = source(node);
+        if (!body)
+            continue;
+        const parsed = (0, request_evidence_1.lexEvidenceSource)(body);
+        if (!parsed.valid)
+            continue;
+        const own = inFile(node.filePath);
+        // Component → build is containment, not an invented runtime call.
+        const nested = own.filter(n => n.id !== node.id && n.startLine >= node.startLine && n.endLine <= node.endLine
+            && n.kind === 'method' && n.name === 'build').slice(0, 2);
+        if (depth < 2)
+            queue.push(...nested.map(n => ({ node: n, depth: depth + 1 })));
+        const adjacent = [...graph.getOutgoingEdges(node.id), ...graph.getIncomingEdges(node.id)];
+        reads += 2;
+        for (const edge of adjacent.slice(0, 80)) {
+            if (groups.length >= 24)
+                break;
+            const scope = (0, evidence_paths_1.isArkuiScopeEdge)(edge);
+            const outgoing = edge.source === node.id;
+            if (!scope && !(outgoing && TYPES.has(edge.kind)))
+                continue;
+            const key = JSON.stringify([edge.source, edge.target, edge.kind, edge.metadata]);
+            if (seenEdges.has(key))
+                continue;
+            seenEdges.add(key);
+            const other = graph.getNode(outgoing ? edge.target : edge.source);
+            if (!other || other.filePath.startsWith('ohos-sdk:'))
+                continue;
+            groups.push({ id: `impl-edge:${groups.length}`, label: `${scope ? 'render/navigation scope' : 'type dependency'}: ${node.name} ↔ ${other.name}`,
+                nodes: [node, other], edges: [edge], missing: [], notes: scope
+                    ? ['Static wiring only; enclosing conditions and other shared users remain relevant.'] : [] });
+            // Do not fan out from a shared caller into its unrelated siblings.
+            if (outgoing && depth < 2)
+                queue.push({ node: other, depth: depth + 1 });
+        }
+        if (adjacent.length > 80)
+            groups.push({ id: `impl-limit:${node.id}`, label: 'context expansion limit', nodes: [node], edges: [],
+                notes: [], missing: [`additional relationships at ${at(node)}`] });
+        for (const imp of own.filter(n => n.kind === 'import').slice(0, 40)) {
+            if (groups.length >= 24 || seenImports.has(imp.id) || !uses(parsed.code, imp.name))
+                continue;
+            seenImports.add(imp.id);
+            const importSource = source(imp);
+            if (!importSource)
+                continue;
+            const importCode = (0, request_evidence_1.lexEvidenceSource)(importSource);
+            const match = [...importSource.matchAll(/\bimport\s+([\s\S]*?)\s+from\s*['"]([^'"\r\n]+)['"]/g)]
+                .find(m => importCode.valid && importCode.code.slice(m.index).startsWith('import'));
+            if (!match)
+                continue;
+            const clause = match[1];
+            const module = match[2];
+            const aliases = [...clause.matchAll(/([\w$]+)\s+as\s+([\w$]+)/g)];
+            const name = aliases.find(a => a[2] === imp.name)?.[1] ?? imp.name;
+            const group = { id: `impl-import:${imp.id}`, label: `import ${imp.name} from ${module}`,
+                nodes: [node, imp], edges: [], notes: [], missing: [] };
+            const links = graph.getOutgoingEdges(imp.id).filter(e => e.kind === 'imports');
+            reads++;
+            for (const link of links.slice(0, 4)) {
+                const target = graph.getNode(link.target);
+                if (!target || target.filePath.startsWith('ohos-sdk:'))
+                    continue;
+                const pool = target.kind === 'file' ? inFile(target.filePath) : [target];
+                const matches = pool.filter(n => DECLARATIONS.has(n.kind) && n.name === name);
+                const unique = [...new Map(matches.map(n => [`${n.filePath}:${n.startLine}:${n.name}`, n])).values()];
+                if (unique.length === 1) {
+                    group.nodes.push(unique[0]);
+                    group.edges.push(link);
+                }
+                // Export declarations are evidence of the public boundary, never proof that every file-local name is exported.
+                const exports = pool.filter(n => n.kind === 'export' && (n.name === name || uses(n.signature ?? '', name))).slice(0, 3);
+                group.nodes.push(...exports);
+            }
+            if (group.nodes.length === 2) {
+                const binding = module.startsWith('.') ? undefined : moduleBinding?.(imp.filePath, module);
+                const chains = relativeDefinition(imp.filePath, binding?.relativePath ?? module, name);
+                if (chains.length === 1)
+                    group.nodes.push(...(binding?.witnesses ?? []), ...chains[0]);
+                else if (chains.length > 1)
+                    group.missing.push(`ambiguous export ${name} from ${module}`);
+            }
+            if (group.nodes.length === 2 && /^@(?:kit|ohos|hms)\./.test(module) && sdkModule) {
+                if (!sdkCache.has(module))
+                    sdkCache.set(module, sdkModule(module));
+                const sdk = sdkCache.get(module);
+                if (sdk) {
+                    const memberNames = new Set([name]);
+                    for (const m of parsed.code.matchAll(new RegExp(`\\b${esc(imp.name)}\\s*\\.\\s*([\\w$]+)`, 'g')))
+                        memberNames.add(m[1]);
+                    const sdkNodes = sdk.nodes.filter(n => n.signature && memberNames.has(n.name));
+                    // Complete parameter objects are a group: include declared fields of referenced types.
+                    const signature = sdkNodes.map(n => n.signature).join('\n');
+                    const types = sdk.nodes.filter(n => ['interface', 'class', 'type_alias', 'enum'].includes(n.kind) && uses(signature, n.name));
+                    const selected = [...new Map([...sdkNodes, ...types, ...sdk.nodes.filter(n => types.some(t => n.filePath === t.filePath && n.startLine >= t.startLine && n.endLine <= t.endLine))].map(n => [n.id, n])).values()];
+                    if (selected.length && selected.length <= 32) {
+                        group.sdk = { module, version: sdk.version, nodes: selected };
+                        group.notes.push('Bounded SDK signature bundle; inherited/indirect types, API availability and runtime requirements remain unverified.');
+                    }
+                    else
+                        group.missing.push(`SDK signature/type closure for ${module}.${name}`);
+                }
+            }
+            if (group.nodes.length === 2 && !group.sdk)
+                group.missing.push(`resolved definition/export of ${imp.name} from ${module} (${at(imp)})`);
+            group.notes.push('Import/definition evidence does not prove module installation or public export availability.');
+            groups.push(group);
+        }
+    }
+    if (queue.length)
+        groups.push({ id: 'impl-limit', label: 'context expansion limit', nodes: [], edges: [], notes: [],
+            missing: [at(queue[0].node)] });
+    return groups;
+}
+//# sourceMappingURL=implementation-context.js.map

package/dist/mcp/index-availability.d.ts

@@ -28,4 +28,26 @@ export declare function resolveProductIndexState(cg: HomeGraph): ProductIndexSta
 export declare function isSqliteBusyMessage(message: string): boolean;
 /** True when text is already a pure (or leading) HomeGraph status line. */
 export declare function textAlreadyHasProductStatus(text: string): boolean;
+/** Marker line for Spec 0038 project-root path hint (idempotent prepend). */
+export declare const PROJECT_ROOT_HINT_MARKER = "HomeGraph project root:";
+/**
+ * Short preamble: absolute project root + how to join repo-relative paths (Spec 0038).
+ * `absRoot` should already be resolved (platform-native absolute path).
+ */
+export declare function formatProjectRootPathHint(absRoot: string): string;
+/** True when text already carries a Spec 0038 project-root hint. */
+export declare function textAlreadyHasProjectRootHint(text: string): boolean;
+/** Marker for Spec 0043 bound-root projectPath soft-pin notice (idempotent prepend). */
+export declare const BOUND_PROJECT_PATH_PIN_MARKER = "This MCP session is bound to";
+/**
+ * English preamble when a tool `projectPath` resolves to a different index root
+ * than the MCP session's default bound root (Spec 0043). Success-shaped — not isError.
+ */
+export declare function formatBoundProjectPathPinNotice(opts: {
+    boundRoot: string;
+    requestedPath: string;
+    resolvedRoot: string | null;
+}): string;
+/** True when text already carries a Spec 0043 pin notice. */
+export declare function textAlreadyHasBoundProjectPathPinNotice(text: string): boolean;
 //# sourceMappingURL=index-availability.d.ts.map

package/dist/mcp/index-availability.js

@@ -6,12 +6,16 @@
  * pending dirty files) to the five states hosts and agents should see.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PRODUCT_STATUS_GLOSSARY = void 0;
+exports.BOUND_PROJECT_PATH_PIN_MARKER = exports.PROJECT_ROOT_HINT_MARKER = exports.PRODUCT_STATUS_GLOSSARY = void 0;
 exports.productIndexGuidance = productIndexGuidance;
 exports.formatProductStatusLine = formatProductStatusLine;
 exports.resolveProductIndexState = resolveProductIndexState;
 exports.isSqliteBusyMessage = isSqliteBusyMessage;
 exports.textAlreadyHasProductStatus = textAlreadyHasProductStatus;
+exports.formatProjectRootPathHint = formatProjectRootPathHint;
+exports.textAlreadyHasProjectRootHint = textAlreadyHasProjectRootHint;
+exports.formatBoundProjectPathPinNotice = formatBoundProjectPathPinNotice;
+exports.textAlreadyHasBoundProjectPathPinNotice = textAlreadyHasBoundProjectPathPinNotice;
 /** One-line glossary for MCP initialize / tool surface (Spec 0035). */
 exports.PRODUCT_STATUS_GLOSSARY = 'status: empty=not ready · fast=map only (homegraph_project) · full=fresh · dirty=usable but listed paths outdated · syncing=write lock, retry';
 const MAX_DIRTY_PATHS = 5;
@@ -102,4 +106,39 @@ function isSqliteBusyMessage(message) {
 function textAlreadyHasProductStatus(text) {
     return /^\s*HomeGraph status=/m.test(text);
 }
+/** Marker line for Spec 0038 project-root path hint (idempotent prepend). */
+exports.PROJECT_ROOT_HINT_MARKER = 'HomeGraph project root:';
+/**
+ * Short preamble: absolute project root + how to join repo-relative paths (Spec 0038).
+ * `absRoot` should already be resolved (platform-native absolute path).
+ */
+function formatProjectRootPathHint(absRoot) {
+    const root = absRoot.trim();
+    return (`${exports.PROJECT_ROOT_HINT_MARKER} \`${root}\`\n` +
+        'Paths below are repo-relative to that root. Pass them to Read/Grep as-is, or join as `<root>/<relative>` (use `/`). Do not invent experiment/result directory prefixes.');
+}
+/** True when text already carries a Spec 0038 project-root hint. */
+function textAlreadyHasProjectRootHint(text) {
+    return text.includes(exports.PROJECT_ROOT_HINT_MARKER);
+}
+/** Marker for Spec 0043 bound-root projectPath soft-pin notice (idempotent prepend). */
+exports.BOUND_PROJECT_PATH_PIN_MARKER = 'This MCP session is bound to';
+/**
+ * English preamble when a tool `projectPath` resolves to a different index root
+ * than the MCP session's default bound root (Spec 0043). Success-shaped — not isError.
+ */
+function formatBoundProjectPathPinNotice(opts) {
+    const bound = opts.boundRoot.trim();
+    const requested = opts.requestedPath.trim();
+    const resolved = opts.resolvedRoot === null
+        ? 'no .homegraph/ found walking up from it'
+        : `resolves to \`${opts.resolvedRoot.trim()}\``;
+    return (`${exports.BOUND_PROJECT_PATH_PIN_MARKER} \`${bound}\`.\n` +
+        `Ignoring projectPath=\`${requested}\` (${resolved}).\n` +
+        'Results below are from the bound project root only. Omit projectPath, or pass a path under that root.');
+}
+/** True when text already carries a Spec 0043 pin notice. */
+function textAlreadyHasBoundProjectPathPinNotice(text) {
+    return text.includes(exports.BOUND_PROJECT_PATH_PIN_MARKER);
+}
 //# sourceMappingURL=index-availability.js.map