homegraph 1.5.10 → 1.6.1

package/dist/mcp/index.js

@@ -73,6 +73,7 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
 const directory_1 = require("../directory");
+const runtime_log_1 = require("../runtime-log");
 const transport_1 = require("./transport");
 const engine_1 = require("./engine");
 const session_1 = require("./session");
@@ -298,6 +299,7 @@ class MCPServer {
             // Runs until the host disconnects; the proxy installs its own watchdog and
             // falls back to an in-process engine if the daemon never comes up.
             this.mode = 'proxy';
+            (0, runtime_log_1.logLifecycle)('mcp.start', { projectRoot: root, mode: 'proxy' });
             await this.runProxyWithLocalHandshake(root);
             return;
         }
@@ -306,6 +308,7 @@ class MCPServer {
             // is still safe to recover from with a direct-mode session.
             const msg = err instanceof Error ? err.message : String(err);
             process.stderr.write(`[HomeGraph MCP] Proxy path failed (${msg}); falling back to direct mode.\n`);
+            (0, runtime_log_1.logLifecycleError)('mcp.proxy.fail', { projectRoot: root, msg });
             return this.startDirect('proxy path threw');
         }
     }
@@ -346,6 +349,11 @@ class MCPServer {
         if (reason && process.env.HOMEGRAPH_MCP_DEBUG) {
             process.stderr.write(`[HomeGraph MCP] Direct mode: ${reason}.\n`);
         }
+        (0, runtime_log_1.logLifecycle)('mcp.start', {
+            projectRoot: this.projectPath ?? undefined,
+            mode: 'direct',
+            reason,
+        });
         // Direct mode = one client. Do NOT start a query-pool worker: each worker
         // is a second V8 isolate + a second open of the project DB, and on large
         // indexes (hundreds of MB) that alone pushed process-tree RSS to ~5GB.
@@ -392,6 +400,7 @@ class MCPServer {
      */
     async startDaemonProcess() {
         const root = resolveDaemonRoot(this.projectPath) ?? this.projectPath ?? process.cwd();
+        (0, runtime_log_1.logLifecycle)('mcp.start', { projectRoot: root, mode: 'daemon' });
         for (let attempt = 0; attempt < TAKEOVER_MAX_RETRIES; attempt++) {
             const lock = (0, daemon_1.tryAcquireDaemonLock)(root);
             if (lock.kind === 'acquired') {

package/dist/mcp/indexable-root.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Cheap “is this root worth creating a HomeGraph index?” probe (Spec 0049).
+ *
+ * Used by MCP auto-init to avoid writing `.homegraph/` into empty workspaces
+ * (e.g. DevEco Code task dirs before `devecocli create`).
+ */
+/**
+ * True when `root` already looks like a project HomeGraph should index.
+ * Short-circuits on root `build-profile.json5`, else bounded BFS for any
+ * {@link isSourceFile} hit. Ignores `.homegraph*` and common build/vendor dirs.
+ */
+export declare function isIndexableRoot(rootDir: string, opts?: {
+    maxDirs?: number;
+    maxDepth?: number;
+}): boolean;
+/**
+ * Parse `HOMEGRAPH_DEFER_PROBE_MS`. Default **60000**.
+ * `0` disables the timer (tool-call kick only). Invalid → default.
+ * Clamp: 0, or 1000ms … 10min.
+ */
+export declare function parseDeferProbeMs(raw: string | undefined): number;
+//# sourceMappingURL=indexable-root.d.ts.map

package/dist/mcp/indexable-root.js

@@ -0,0 +1,140 @@
+"use strict";
+/**
+ * Cheap “is this root worth creating a HomeGraph index?” probe (Spec 0049).
+ *
+ * Used by MCP auto-init to avoid writing `.homegraph/` into empty workspaces
+ * (e.g. DevEco Code task dirs before `devecocli create`).
+ */
+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.isIndexableRoot = isIndexableRoot;
+exports.parseDeferProbeMs = parseDeferProbeMs;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const grammars_1 = require("../extraction/grammars");
+const directory_1 = require("../directory");
+const HARMONY_PROFILE = 'build-profile.json5';
+/** Dirs skipped during the bounded source walk (names only). */
+const SKIP_DIR_NAMES = new Set([
+    'node_modules',
+    'oh_modules',
+    '.git',
+    '.hvigor',
+    '.preview',
+    '.cxx',
+    'dist',
+    'build',
+    'out',
+    'coverage',
+    'vendor',
+    'Pods',
+    'DerivedData',
+    '__pycache__',
+    '.venv',
+    'venv',
+    'target',
+    '.gradle',
+    'obj',
+]);
+const DEFAULT_MAX_DIRS = 4000;
+const DEFAULT_MAX_DEPTH = 8;
+/**
+ * True when `root` already looks like a project HomeGraph should index.
+ * Short-circuits on root `build-profile.json5`, else bounded BFS for any
+ * {@link isSourceFile} hit. Ignores `.homegraph*` and common build/vendor dirs.
+ */
+function isIndexableRoot(rootDir, opts) {
+    const root = path.resolve(rootDir);
+    let st;
+    try {
+        st = fs.statSync(root);
+    }
+    catch {
+        return false;
+    }
+    if (!st.isDirectory())
+        return false;
+    if (fs.existsSync(path.join(root, HARMONY_PROFILE)))
+        return true;
+    const maxDirs = opts?.maxDirs ?? DEFAULT_MAX_DIRS;
+    const maxDepth = opts?.maxDepth ?? DEFAULT_MAX_DEPTH;
+    const queue = [{ dir: root, depth: 0 }];
+    let dirsSeen = 0;
+    while (queue.length > 0 && dirsSeen < maxDirs) {
+        const { dir, depth } = queue.shift();
+        dirsSeen += 1;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const ent of entries) {
+            const name = ent.name;
+            if (name === '.' || name === '..')
+                continue;
+            if ((0, directory_1.isHomeGraphDataDir)(name) || SKIP_DIR_NAMES.has(name))
+                continue;
+            const full = path.join(dir, name);
+            if (ent.isDirectory()) {
+                if (depth + 1 <= maxDepth)
+                    queue.push({ dir: full, depth: depth + 1 });
+                continue;
+            }
+            if (ent.isFile() && (0, grammars_1.isSourceFile)(full))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Parse `HOMEGRAPH_DEFER_PROBE_MS`. Default **60000**.
+ * `0` disables the timer (tool-call kick only). Invalid → default.
+ * Clamp: 0, or 1000ms … 10min.
+ */
+function parseDeferProbeMs(raw) {
+    if (raw === undefined || !raw.trim())
+        return 60_000;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || !Number.isInteger(n))
+        return 60_000;
+    if (n === 0)
+        return 0;
+    if (n < 1000 || n > 10 * 60 * 1000)
+        return 60_000;
+    return n;
+}
+//# sourceMappingURL=indexable-root.js.map

package/dist/mcp/liveness-watchdog.d.ts

@@ -7,6 +7,11 @@ export declare const DEFAULT_WATCHDOG_TIMEOUT_MS = 60000;
  * beyond any legitimate statement). 10× the 60s default ⇒ 10 minutes.
  */
 export declare const PROGRESS_CAP_MULTIPLIER = 10;
+/**
+ * Spec 0047: liveness watchdog is opt-in.
+ * Armed only when `HOMEGRAPH_WATCHDOG` is truthy and `HOMEGRAPH_NO_WATCHDOG` is not.
+ */
+export declare function isLivenessWatchdogEnabled(env?: NodeJS.ProcessEnv): boolean;
 /** Parse the timeout env, falling back to the default for missing/invalid values. */
 export declare function parseWatchdogTimeoutMs(raw: string | undefined, fallback?: number): number;
 /** Derive a heartbeat cadence that emits several beats inside the timeout window. */
@@ -42,7 +47,7 @@ export declare function installMainThreadWatchdog(options?: WatchdogOptions): Wa
  * resume function. Nested calls refcount; a `stop()` while suspended cancels
  * the pending re-arm.
  *
- * No-op when nothing is armed (tests, `HOMEGRAPH_NO_WATCHDOG`, library embeds).
+ * No-op when nothing is armed (tests, default-off Spec 0047, `HOMEGRAPH_NO_WATCHDOG`, library embeds).
  */
 export declare function suspendLivenessWatchdog(): () => void;
 /**

package/dist/mcp/liveness-watchdog.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PROGRESS_CAP_MULTIPLIER = exports.DEFAULT_WATCHDOG_TIMEOUT_MS = void 0;
+exports.isLivenessWatchdogEnabled = isLivenessWatchdogEnabled;
 exports.parseWatchdogTimeoutMs = parseWatchdogTimeoutMs;
 exports.deriveCheckIntervalMs = deriveCheckIntervalMs;
 exports.installMainThreadWatchdog = installMainThreadWatchdog;
@@ -73,8 +74,9 @@ exports.runWithoutLivenessWatchdog = runWithoutLivenessWatchdog;
  * (off-thread) and the daemon's indexing shells out to a child process, so the
  * daemon's main thread only ever does fast, bounded work. The default timeout
  * is ~300× the 5h #850 wedge shorter, yet far longer than any legitimate
- * main-thread block. Opt out with `HOMEGRAPH_NO_WATCHDOG=1`; tune with
- * `HOMEGRAPH_WATCHDOG_TIMEOUT_MS`.
+ * main-thread block. Spec 0047: **opt in** with `HOMEGRAPH_WATCHDOG=1` (default
+ * off for product / DevEco concurrent init); `HOMEGRAPH_NO_WATCHDOG=1` still
+ * forces off. Tune with `HOMEGRAPH_WATCHDOG_TIMEOUT_MS`.
  *
  * **Disk-progress deferral (`progressPaths`).** The CLI `index`/`init` path is
  * different: it runs the SQLite store on this thread, and one long synchronous
@@ -118,6 +120,15 @@ function isEnvTruthy(raw) {
         return false;
     return ['1', 'true', 'yes', 'on'].includes(raw.trim().toLowerCase());
 }
+/**
+ * Spec 0047: liveness watchdog is opt-in.
+ * Armed only when `HOMEGRAPH_WATCHDOG` is truthy and `HOMEGRAPH_NO_WATCHDOG` is not.
+ */
+function isLivenessWatchdogEnabled(env = process.env) {
+    if (isEnvTruthy(env.HOMEGRAPH_NO_WATCHDOG))
+        return false;
+    return isEnvTruthy(env.HOMEGRAPH_WATCHDOG);
+}
 /** Parse the timeout env, falling back to the default for missing/invalid values. */
 function parseWatchdogTimeoutMs(raw, fallback = exports.DEFAULT_WATCHDOG_TIMEOUT_MS) {
     if (raw === undefined)
@@ -153,7 +164,7 @@ const capMs = Number(process.argv[3]);
 const progressPaths = process.argv.slice(4);
 const secs = Math.round(timeoutMs / 1000);
 function kill(extra) {
-  try { fs.writeSync(2, Buffer.from('[HomeGraph] Main thread unresponsive for ~' + secs + 's' + (extra || '') + ' — killing the wedged process so a fresh one can start (#850). Disable with HOMEGRAPH_NO_WATCHDOG=1.\\n')); } catch (e) {}
+  try { fs.writeSync(2, Buffer.from('[HomeGraph] Main thread unresponsive for ~' + secs + 's' + (extra || '') + ' — killing the wedged process so a fresh one can start (#850). Disable with HOMEGRAPH_NO_WATCHDOG=1 (default off; enable with HOMEGRAPH_WATCHDOG=1).\\n')); } catch (e) {}
   try { process.kill(parentPid, 'SIGKILL'); } catch (e) {}
   process.exit(0);
 }
@@ -318,7 +329,8 @@ function rearmFromOptions(options) {
  * current generation.
  */
 function installMainThreadWatchdog(options = {}) {
-    if (isEnvTruthy(process.env.HOMEGRAPH_NO_WATCHDOG))
+    // Spec 0047: default off — set HOMEGRAPH_WATCHDOG=1 to arm.
+    if (!isLivenessWatchdogEnabled())
         return null;
     // Replace any prior generation (including a mid-suspend pending re-arm).
     suspendDepth = 0;
@@ -336,7 +348,7 @@ function installMainThreadWatchdog(options = {}) {
  * resume function. Nested calls refcount; a `stop()` while suspended cancels
  * the pending re-arm.
  *
- * No-op when nothing is armed (tests, `HOMEGRAPH_NO_WATCHDOG`, library embeds).
+ * No-op when nothing is armed (tests, default-off Spec 0047, `HOMEGRAPH_NO_WATCHDOG`, library embeds).
  */
 function suspendLivenessWatchdog() {
     suspendDepth++;

package/dist/mcp/locate-contract.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Spec 0044 — explore locate contract helpers (Located / Miss / Partial,
+ * literal-first demotion of log/toast spines, filename≠declaration hint,
+ * depth-fuse exemption for already-located symbols).
+ */
+import type { ExploreEmission, ExploreCallRecord, ExploreProjectState } from './explore-session-state';
+export type LocateOutcome = 'located' | 'partial' | 'miss';
+/** Marker strings (idempotent checks). */
+export declare const LOCATED_MARKER = "**Located**";
+export declare const MISS_MARKER = "**Miss**";
+export declare const FILENAME_DECL_MISMATCH_MARKER = "Filename does not match primary declaration";
+/** Query explicitly names a log/toast API — then those nodes may stay on the spine. */
+export declare function queryNamesLogOrToast(query: string): boolean;
+export declare function isLogOrToastSpineName(name: string): boolean;
+/** Demote log/toast when the user did not ask for them. */
+export declare function shouldDemoteLogToastSpine(name: string, query: string): boolean;
+/**
+ * Classify locate outcome for explore (Spec 0044 §8–9).
+ * Exact anchor / literal witness beats fuzzy-only FTS.
+ */
+export declare function classifyLocateOutcome(opts: {
+    hasExactAnchorHit: boolean;
+    hasLiteralWitness: boolean;
+    hasFullDeclarations: boolean;
+    missingStaticRelation: boolean;
+    budgetPartial: boolean;
+}): LocateOutcome;
+export declare function formatLocatedBanner(): string;
+export declare function formatPartialBanner(): string;
+/** Miss: paths only, no source bodies. */
+export declare function formatMissBanner(candidatePaths: readonly string[]): string;
+/**
+ * When file basename (sans extension) ≠ primary declaration name.
+ * Returns null when names match or inputs are empty.
+ */
+export declare function formatFilenameDeclarationMismatch(filePath: string, primaryDeclName: string | null | undefined): string | null;
+/** Names recorded on the latest counted explore emission. */
+export declare function locatedNamesFromEmission(emission: ExploreEmission | ExploreCallRecord | null | undefined): string[];
+export declare function symbolMatchesLocatedNames(symbol: string | undefined, locatedNames: readonly string[]): boolean;
+/**
+ * Spec 0044 §10.2 — do not depth-fuse-refuse a symbol already present on the
+ * latest explore locate list (even after Partial spent its one generic drill).
+ */
+export declare function shouldExemptDepthFuseForLocatedSymbol(prior: ExploreProjectState | null | undefined, symbol: string | undefined): boolean;
+/** Strip CJK→ASCII synonym seeds when Miss-bound (Spec 0044 §9). */
+export declare function shouldSuppressSynonymExpansion(opts: {
+    hasExactAnchorHit: boolean;
+    hasLiteralWitness: boolean;
+}): boolean;
+//# sourceMappingURL=locate-contract.d.ts.map

package/dist/mcp/locate-contract.js

@@ -0,0 +1,146 @@
+"use strict";
+/**
+ * Spec 0044 — explore locate contract helpers (Located / Miss / Partial,
+ * literal-first demotion of log/toast spines, filename≠declaration hint,
+ * depth-fuse exemption for already-located symbols).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FILENAME_DECL_MISMATCH_MARKER = exports.MISS_MARKER = exports.LOCATED_MARKER = void 0;
+exports.queryNamesLogOrToast = queryNamesLogOrToast;
+exports.isLogOrToastSpineName = isLogOrToastSpineName;
+exports.shouldDemoteLogToastSpine = shouldDemoteLogToastSpine;
+exports.classifyLocateOutcome = classifyLocateOutcome;
+exports.formatLocatedBanner = formatLocatedBanner;
+exports.formatPartialBanner = formatPartialBanner;
+exports.formatMissBanner = formatMissBanner;
+exports.formatFilenameDeclarationMismatch = formatFilenameDeclarationMismatch;
+exports.locatedNamesFromEmission = locatedNamesFromEmission;
+exports.symbolMatchesLocatedNames = symbolMatchesLocatedNames;
+exports.shouldExemptDepthFuseForLocatedSymbol = shouldExemptDepthFuseForLocatedSymbol;
+exports.shouldSuppressSynonymExpansion = shouldSuppressSynonymExpansion;
+const explore_session_state_1 = require("./explore-session-state");
+const explore_repeat_guard_1 = require("./explore-repeat-guard");
+/** Marker strings (idempotent checks). */
+exports.LOCATED_MARKER = '**Located**';
+exports.MISS_MARKER = '**Miss**';
+exports.FILENAME_DECL_MISMATCH_MARKER = 'Filename does not match primary declaration';
+const LOG_TOAST_NAME_RE = /^(?:Logger|Hilog|HiLog|Toast|promptAction|log(?:Info|Error|Warn|Debug|Fatal)?|hilog)$/i;
+/** Query explicitly names a log/toast API — then those nodes may stay on the spine. */
+function queryNamesLogOrToast(query) {
+    return /\b(?:Logger|hilog|HiLog|Toast|promptAction|logInfo|logError|logWarn|logDebug)\b/i.test(query)
+        || /日志|弹窗|吐司/.test(query);
+}
+function isLogOrToastSpineName(name) {
+    return LOG_TOAST_NAME_RE.test(name.trim());
+}
+/** Demote log/toast when the user did not ask for them. */
+function shouldDemoteLogToastSpine(name, query) {
+    return isLogOrToastSpineName(name) && !queryNamesLogOrToast(query);
+}
+/**
+ * Classify locate outcome for explore (Spec 0044 §8–9).
+ * Exact anchor / literal witness beats fuzzy-only FTS.
+ */
+function classifyLocateOutcome(opts) {
+    if (!opts.hasExactAnchorHit && !opts.hasLiteralWitness)
+        return 'miss';
+    if (opts.budgetPartial || opts.missingStaticRelation)
+        return 'partial';
+    if (opts.hasFullDeclarations && (opts.hasExactAnchorHit || opts.hasLiteralWitness)) {
+        return 'located';
+    }
+    return 'partial';
+}
+function formatLocatedBanner() {
+    return (`> ${exports.LOCATED_MARKER} — exact anchor declaration(s) are in this reply. `
+        + 'Reuse them; do **not** Grep the same symbol names again. '
+        + 'Runtime behavior may still need validation after edits.');
+}
+function formatPartialBanner() {
+    return ('> **Partial** — evidence is incomplete (missing relation or budget). '
+        + 'Next: `homegraph_node` / `homegraph_usages` / `homegraph_search` for the named gap — '
+        + 'do **not** Grep the same symbol names already shown.');
+}
+/** Miss: paths only, no source bodies. */
+function formatMissBanner(candidatePaths) {
+    const paths = candidatePaths
+        .map((p) => p.replace(/\\/g, '/').trim())
+        .filter(Boolean)
+        .slice(0, 12);
+    const list = paths.length
+        ? paths.map((p) => `- \`${p}\``).join('\n')
+        : '- _(no fuzzy path candidates)_';
+    return [
+        `> ${exports.MISS_MARKER} — no exact in-repo anchor or literal witness. Source bodies omitted.`,
+        'Fuzzy candidate paths (no source):',
+        list,
+        'Next: `homegraph_search` with a more precise symbol, file basename, or quoted UI label.',
+    ].join('\n');
+}
+/**
+ * When file basename (sans extension) ≠ primary declaration name.
+ * Returns null when names match or inputs are empty.
+ */
+function formatFilenameDeclarationMismatch(filePath, primaryDeclName) {
+    if (!primaryDeclName?.trim())
+        return null;
+    const base = filePath.replace(/\\/g, '/').split('/').pop() ?? '';
+    const stem = base.replace(/\.[^.]+$/, '');
+    if (!stem)
+        return null;
+    const norm = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, '');
+    if (norm(stem) === norm(primaryDeclName))
+        return null;
+    return (`> ⚠ ${exports.FILENAME_DECL_MISMATCH_MARKER}: file \`${stem}\` vs \`${primaryDeclName.trim()}\` — `
+        + 'prefer the declaration name for edits and follow-up queries.');
+}
+/** Names recorded on the latest counted explore emission. */
+function locatedNamesFromEmission(emission) {
+    if (!emission?.locatedNodes?.length)
+        return [];
+    const out = new Set();
+    for (const n of emission.locatedNodes) {
+        if (n?.name)
+            out.add(n.name);
+        if (n?.qualifiedName) {
+            out.add(n.qualifiedName);
+            const leaf = n.qualifiedName.split(/[.::]/).pop();
+            if (leaf)
+                out.add(leaf);
+        }
+    }
+    return [...out];
+}
+function symbolMatchesLocatedNames(symbol, locatedNames) {
+    const raw = symbol?.trim();
+    if (!raw || locatedNames.length === 0)
+        return false;
+    const needle = raw.toLowerCase();
+    const leaf = needle.split(/[.::]/).pop() ?? needle;
+    for (const n of locatedNames) {
+        const ln = n.toLowerCase();
+        if (ln === needle || ln === leaf)
+            return true;
+        if (ln.endsWith(`.${leaf}`) || ln.endsWith(`::${leaf}`))
+            return true;
+    }
+    return false;
+}
+/**
+ * Spec 0044 §10.2 — do not depth-fuse-refuse a symbol already present on the
+ * latest explore locate list (even after Partial spent its one generic drill).
+ */
+function shouldExemptDepthFuseForLocatedSymbol(prior, symbol) {
+    const last = (0, explore_repeat_guard_1.latestCountedExplore)(prior);
+    if (!last)
+        return false;
+    // Closed explores already skip the fuse; exemption matters for Partial/Miss.
+    if ((0, explore_session_state_1.inferExploreEvidenceStatus)(last) === 'complete')
+        return false;
+    return symbolMatchesLocatedNames(symbol, locatedNamesFromEmission(last));
+}
+/** Strip CJK→ASCII synonym seeds when Miss-bound (Spec 0044 §9). */
+function shouldSuppressSynonymExpansion(opts) {
+    return !opts.hasExactAnchorHit && !opts.hasLiteralWitness;
+}
+//# sourceMappingURL=locate-contract.js.map

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

@@ -1,21 +1,7 @@
-/**
- * MCP query cache — memory key index + serialized tool responses in homegraph.db.
- *
- * A per-project in-memory Set of cache keys gives O(1) negative lookup so misses
- * skip the SQLite SELECT. Payloads stay in homegraph.db; the Set is warmed from
- * DB on first use after daemon restart when the index stamp is still valid.
- *
- * Invalidated wholesale when the index stamp or cache format version changes.
- * Per-call staleness/worktree notices are applied AFTER cache lookup so hits
- * stay fresh.
- *
- * The key Set lives on the daemon main thread only (cache read/write runs there
- * before/after worker-pool explore dispatch), so no cross-thread locking is needed.
- */
 import type { QueryBuilder } from '../db/queries';
 import type { ToolResult } from './tools';
 /** Bump when cache-key normalization or cached payload shape changes. */
-export declare const QUERY_CACHE_FORMAT_VERSION = 5;
+export declare const QUERY_CACHE_FORMAT_VERSION = 7;
 export declare function isMcpQueryCacheEnabled(): boolean;
 export declare function isCacheableMcpTool(toolName: string): boolean;
 /**

package/dist/mcp/query-cache.js

@@ -1,4 +1,14 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpQueryCacheIndex = exports.QUERY_CACHE_FORMAT_VERSION = void 0;
+exports.isMcpQueryCacheEnabled = isMcpQueryCacheEnabled;
+exports.isCacheableMcpTool = isCacheableMcpTool;
+exports.getMcpQueryCacheIndex = getMcpQueryCacheIndex;
+exports.resetMcpQueryCacheIndices = resetMcpQueryCacheIndices;
+exports.normalizeExploreQueryTerms = normalizeExploreQueryTerms;
+exports.buildMcpQueryCacheFingerprint = buildMcpQueryCacheFingerprint;
+exports.buildMcpQueryCacheKey = buildMcpQueryCacheKey;
+const request_contract_1 = require("../search/request-contract");
 /**
  * MCP query cache — memory key index + serialized tool responses in homegraph.db.
  *
@@ -13,15 +23,6 @@
  * The key Set lives on the daemon main thread only (cache read/write runs there
  * before/after worker-pool explore dispatch), so no cross-thread locking is needed.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.McpQueryCacheIndex = exports.QUERY_CACHE_FORMAT_VERSION = void 0;
-exports.isMcpQueryCacheEnabled = isMcpQueryCacheEnabled;
-exports.isCacheableMcpTool = isCacheableMcpTool;
-exports.getMcpQueryCacheIndex = getMcpQueryCacheIndex;
-exports.resetMcpQueryCacheIndices = resetMcpQueryCacheIndices;
-exports.normalizeExploreQueryTerms = normalizeExploreQueryTerms;
-exports.buildMcpQueryCacheFingerprint = buildMcpQueryCacheFingerprint;
-exports.buildMcpQueryCacheKey = buildMcpQueryCacheKey;
 const node_crypto_1 = require("node:crypto");
 const query_plan_1 = require("../search/query-plan");
 const PLAN_RELATIONS = new Set(query_plan_1.QUERY_RELATIONS);
@@ -35,7 +36,7 @@ function defaultExploreMaxFiles(fileCount) {
     return 8;
 }
 /** Bump when cache-key normalization or cached payload shape changes. */
-exports.QUERY_CACHE_FORMAT_VERSION = 5;
+exports.QUERY_CACHE_FORMAT_VERSION = 7;
 const METADATA_INDEX_STAMP = 'query_cache_index_stamp';
 const METADATA_FORMAT_VERSION = 'query_cache_format_version';
 /** Tools that must stay live — never cached. */
@@ -146,7 +147,7 @@ function exploreEnvFingerprint() {
     const fullSource = process.env.HOMEGRAPH_EXPLORE_FULL_SOURCE === '1' ? '1' : '0';
     const evidencePacks = process.env.HOMEGRAPH_ARKTS_EVIDENCE_PACKS === '0' ? '0' : '1';
     const queryPaths = process.env.HOMEGRAPH_ARKTS_QUERY_PATHS === '0' ? '0' : '1';
-    return `linums:${linums}|adaptive:${adaptive}|rankMultiterm:${rankMultiterm}|fullSource:${fullSource}|arktsEvidence:${evidencePacks}|arktsPaths:${queryPaths}`;
+    return `implementationContext:${process.env.HOMEGRAPH_ARKTS_IMPLEMENTATION_CONTEXT === '0' ? '0' : '1'}|controlEvidence:${process.env.HOMEGRAPH_ARKTS_CONTROL_EVIDENCE === '0' ? '0' : '1'}|linums:${linums}|adaptive:${adaptive}|rankMultiterm:${rankMultiterm}|fullSource:${fullSource}|arktsEvidence:${evidencePacks}|arktsPaths:${queryPaths}|accuracyTargets:${process.env.HOMEGRAPH_ACCURACY_TARGETS === '0' ? '0' : '1'}|accuracyCoverage:${process.env.HOMEGRAPH_ACCURACY_COVERAGE === '0' ? '0' : '1'}`;
 }
 function normalizeString(value) {
     if (typeof value !== 'string')
@@ -213,7 +214,15 @@ function queryPlanFingerprint(value) {
     if (!features || Object.keys(features).length > 64
         || !Object.values(features).every(v => typeof v === 'boolean'))
         return undefined;
+    let requestContract;
+    try {
+        requestContract = (0, request_contract_1.validateRequestContract)(plan.requestContract, originalQuery + '\n' + (query(plan.taskContext) ?? ''));
+    }
+    catch {
+        return undefined;
+    }
     return stableJson({
+        requestContract,
         version: plan.version, originalQuery, canonicalQuery, intent, route,
         taskContext: query(plan.taskContext),
         anchors, searchTerms, steps, features,

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

@@ -0,0 +1,69 @@
+import type { RequestContract, RequestTarget } from '../search/request-contract';
+export interface RequestSource {
+    filePath: string;
+    start: number;
+    source: string;
+}
+interface StringToken {
+    start: number;
+    end: number;
+    value: string;
+}
+interface Lexed {
+    code: string;
+    strings: StringToken[];
+    pairs: Map<number, number>;
+    valid: boolean;
+}
+export interface TargetEvidence {
+    id: string;
+    text: string;
+    presence: RequestTarget['presence'];
+    status: 'observed' | 'ambiguous' | 'not_observed' | 'requested_not_observed';
+    locations: string[];
+    note: string;
+}
+export interface BehaviorEvidence {
+    id: string;
+    text: string;
+    kind: string;
+    status: 'binding_observed' | 'binding_not_observed' | 'unknown';
+    locations: string[];
+    note: string;
+}
+export interface RequestEvidence {
+    scope: 'returned_source_only';
+    runtimeVerified: false;
+    targets: TargetEvidence[];
+    behaviors: BehaviorEvidence[];
+}
+/** Conservative lexical witness reader. It does not evaluate ArkTS or infer data flow.
+ * Mask comments, strings, templates and regular expressions before reading structure.
+ * Escaped/interpolated strings are deliberately not used as exact literal witnesses.
+ */
+export declare function lexEvidenceSource(source: string): Lexed;
+/** Reuse one analysis per verified source unit; no disk reads or model calls. */
+export declare function createRequestEvidenceInspector(contract: RequestContract): {
+    score: (units: RequestSource[]) => number;
+    inspect: (units: RequestSource[]) => RequestEvidence;
+};
+export declare function renderRequestEvidence(evidence: RequestEvidence, targets: boolean, behaviors: boolean): string[];
+export interface ControlEvidence {
+    location: string;
+    control: string;
+    labels: string[];
+    enabled: 'binding_observed' | 'binding_not_observed' | 'unknown';
+    expression?: string;
+    click?: string;
+    state: Array<{
+        expression: string;
+        writeLocations: string[];
+    }>;
+}
+/** An inventory of returned controls, not a natural-language target match or a UI test.
+ * Resource names stay literal: an icon called "undo" is not translated into a task label.
+ */
+export declare function inspectControlEvidence(units: RequestSource[]): ControlEvidence[];
+export declare function renderControlEvidence(rows: ControlEvidence[]): string[];
+export {};
+//# sourceMappingURL=request-evidence.d.ts.map