gitnexus 1.6.9 → 1.6.10-aptos.0

package/dist/mcp/local/local-backend.js

@@ -8,8 +8,10 @@
 import fs from 'fs/promises';
 import path from 'path';
 import { createHash } from 'crypto';
-import { initLbug, executeQuery, executeParameterized, closeLbug, isLbugReady, } from '../../core/lbug/pool-adapter.js';
+import { initLbug, executeQuery, executeParameterized, closeLbug, isLbugReady, statDbIdentity, dbIdentityChanged, } from '../../core/lbug/pool-adapter.js';
+import { queryClassBeanMetadata } from './bean-metadata.js';
 import { isValidQueryParams } from '../../core/lbug/query-params.js';
+import { toDisplayLine } from './line-display.js';
 import { isWalCorruptionError, WAL_RECOVERY_SUGGESTION } from '../../core/lbug/lbug-config.js';
 // Embedding imports are lazy (dynamic import) to avoid loading onnxruntime-node
 // at MCP server startup — crashes on unsupported Node ABI versions (#89)
@@ -24,11 +26,13 @@ import { collectBestChunks } from '../../core/embeddings/types.js';
 import { DEFAULT_MCP_VECTOR_MAX_DISTANCE, getVectorMaxDistance, } from '../../core/embeddings/config.js';
 import { rankExactEmbeddingRows, } from '../../core/embeddings/exact-search.js';
 import { EMBEDDING_TABLE_NAME, EMBEDDING_INDEX_NAME } from '../../core/lbug/schema.js';
-import { getExactScanLimit, isVectorExtensionSupportedByPlatform, } from '../../core/platform/capabilities.js';
+import { getExactScanLimit } from '../../core/platform/capabilities.js';
 import { PhaseTimer } from '../../core/search/phase-timer.js';
+import { ftsDegradedWarning } from '../../core/search/fts-indexes.js';
 import { cjkSegmentationModeMismatch, containsSegmentableCjkRun, getSearchFTSCjkSegmentation, isSupportedCjkSegmentationMode, MAX_CJK_SEGMENTATION_QUERY_LENGTH, } from '../../core/search/cjk-segmentation.js';
 import { checkStalenessAsync, checkCwdMatch } from '../../core/git-staleness.js';
 import { logger } from '../../core/logger.js';
+import { isLocalEmbeddingRuntimeBlockerMessage, isMissingLocalEmbeddingStackMessage, } from '../../core/embeddings/runtime-support.js';
 import { LIST_REPOS_DEFAULT_LIMIT, LIST_REPOS_MAX_LIMIT, EXPLAIN_DEFAULT_LIMIT, EXPLAIN_MAX_LIMIT, PDG_QUERY_DEFAULT_LIMIT, PDG_QUERY_MAX_LIMIT, } from '../tools.js';
 import { findImportCycles } from '../../core/graph/import-cycles.js';
 import { decodeTaintPath } from '../../core/ingestion/taint/path-codec.js';
@@ -64,6 +68,51 @@ function resolveAliasString(canonical, legacy) {
     }
     return undefined;
 }
+const TOOL_STRING_ALIASES = {
+    impact: [{ canonical: 'target', aliases: ['name', 'symbol'] }],
+    context: [{ canonical: 'file_path', aliases: ['file'] }],
+};
+function normalizeToolParams(method, params) {
+    const input = params && typeof params === 'object' ? params : {};
+    const definitions = TOOL_STRING_ALIASES[method];
+    if (!definitions)
+        return { params: input };
+    const normalized = { ...input };
+    for (const { canonical, aliases } of definitions) {
+        const keys = [canonical, ...aliases];
+        const supplied = [];
+        for (const key of keys) {
+            if (!Object.prototype.hasOwnProperty.call(input, key))
+                continue;
+            const value = input[key];
+            // Internal CLI callers materialize omitted optional flags as undefined.
+            if (value === undefined)
+                continue;
+            if (typeof value !== 'string' || !value.trim()) {
+                return { error: `MCP parameter ${method}.${key} must be a non-empty string.` };
+            }
+            supplied.push({ key, value: value.trim() });
+        }
+        const distinctValues = new Set(supplied.map(({ value }) => value));
+        if (distinctValues.size > 1) {
+            return {
+                error: `Conflicting MCP parameters for ${method}.${canonical}: ${supplied
+                    .map(({ key }) => key)
+                    .join(', ')} must agree.`,
+            };
+        }
+        for (const alias of aliases)
+            delete normalized[alias];
+        if (supplied.length > 0)
+            normalized[canonical] = supplied[0].value;
+    }
+    if (method === 'impact' &&
+        typeof normalized.target !== 'string' &&
+        (typeof normalized.target_uid !== 'string' || !normalized.target_uid.trim())) {
+        return { error: 'MCP impact requires target, name, symbol, or target_uid.' };
+    }
+    return { params: normalized };
+}
 // AI context generation is CLI-only (gitnexus analyze)
 // import { generateAIContextFiles } from '../../cli/ai-context.js';
 /**
@@ -71,6 +120,8 @@ function resolveAliasString(canonical, legacy) {
  * Matches common test file patterns across all supported languages.
  */
 export function isTestFilePath(filePath) {
+    if (!filePath)
+        return false;
     const p = filePath.toLowerCase().replace(/\\/g, '/');
     return (p.includes('.test.') ||
         p.includes('.spec.') ||
@@ -152,6 +203,10 @@ export const VALID_RELATION_TYPES = new Set([
     // (WRAPS/FETCHES precedent): the 0.5 unknown-type floor applies there,
     // and the edges carry their own confidence (0.8) in the graph.
     'INJECTS',
+    'ACQUIRES',
+    'READS_RESOURCE',
+    'WRITES_RESOURCE',
+    'USES_TYPE',
 ]);
 /**
  * Relation types the #1858 epistemic-boundary probe keys on. Kept as
@@ -419,6 +474,11 @@ export class LocalBackend {
     // not persist across calls and the staleness check would reinit forever
     // (#2106).
     lastObservedIndexedAt = new Map();
+    // #2614 F1: file identity of the lbug the pool last opened. An atomic swap or
+    // an in-place incremental changes the inode; reiniting on that reinit-covers
+    // the window where meta.indexedAt hasn't caught up (and the incremental case),
+    // so a rebuilt index is never served stale even when the stamp looks current.
+    lastObservedDbIdentity = new Map();
     groupToolSvc = null;
     /**
      * One-shot stderr warnings for sibling-clone drift, keyed by
@@ -434,6 +494,12 @@ export class LocalBackend {
      * stderr noisy per DoD §2.8.
      */
     warnedVectorUnsupported = false;
+    /**
+     * One-shot warning when a pruned or Node-unloadable optional embedding stack
+     * (#2370/#2372) forces semantic search to fall back to BM25 — so the
+     * degradation is visible once instead of silent.
+     */
+    warnedMissingEmbeddingStack = false;
     /**
      * Cross-repo group tools (CLI). Shares logic with MCP `group_*` handlers.
      */
@@ -445,7 +511,7 @@ export class LocalBackend {
                 query: (r, p) => this.query(r, p),
                 impactByUid: (id, uid, d, o) => this.impactByUid(id, uid, d, o),
                 context: (r, p) => this.context(r, p),
-                trace: (r, p) => this.trace(r, p),
+                trace: (r, p) => this.traceForGroup(r, p),
                 resolveSymbol: (r, q) => this.resolveSymbolForGroup(r, q),
                 pdgFlows: (r, anchor, opts) => this.pdgFlowsForGroup(r, anchor, opts),
             };
@@ -453,6 +519,23 @@ export class LocalBackend {
         }
         return this.groupToolSvc;
     }
+    /**
+     * Adapt local `trace` to the group port. The assembled group/cross-repo trace
+     * presents 1-based endpoints (via resolveSymbolForGroup), so convert the hop
+     * lines here too — otherwise one response mixes 1-based endpoints with 0-based
+     * hops (#2380). Single-repo `trace` dispatches directly (not through this
+     * port) and stays 0-based (documented full-parity follow-up).
+     */
+    async traceForGroup(repo, params) {
+        const result = await this.trace(repo, params);
+        const hops = result.hops;
+        if (Array.isArray(hops)) {
+            for (const hop of hops) {
+                hop.startLine = toDisplayLine(hop.startLine);
+            }
+        }
+        return result;
+    }
     /**
      * Adapt the shared symbol resolver to the GroupToolPort contract. Used by the
      * cross-repo trace path to locate which member repo an endpoint lives in and
@@ -470,8 +553,8 @@ export class LocalBackend {
                     name: s.name,
                     type: s.type,
                     filePath: s.filePath,
-                    startLine: s.startLine,
-                    endLine: s.endLine,
+                    startLine: toDisplayLine(s.startLine),
+                    endLine: toDisplayLine(s.endLine),
                 },
             };
         }
@@ -483,7 +566,7 @@ export class LocalBackend {
                     name: c.name,
                     type: c.type,
                     filePath: c.filePath,
-                    startLine: c.startLine,
+                    startLine: toDisplayLine(c.startLine),
                 })),
             };
         }
@@ -681,6 +764,7 @@ export class LocalBackend {
             this.initializedRepos.delete(key);
             this.lastStalenessCheck.delete(key);
             this.lastObservedIndexedAt.delete(key);
+            this.lastObservedDbIdentity.delete(key);
             this.reinitPromises.delete(key);
             closeLbug(key).catch(() => { });
         }
@@ -1040,23 +1124,38 @@ export class LocalBackend {
                 // Reading the flat meta for a branch handle would compare the branch
                 // index's indexedAt against the primary's and thrash the pool (#2106).
                 const meta = await loadMeta(path.dirname(repo.lbugPath));
-                if (!meta)
-                    return;
                 // Compare against the last indexedAt OBSERVED for this pool (keyed by
                 // lbugPath), not the handle's — branch handles are fresh spreads so a
                 // handle mutation would not persist and would reinit on every check.
                 const observed = this.lastObservedIndexedAt.get(poolKey) ?? repo.indexedAt;
-                if (meta.indexedAt && meta.indexedAt !== observed) {
-                    // Index was rebuilt — close stale connection and re-init.
-                    // Wrap in reinitPromises to prevent TOCTOU race where concurrent
-                    // callers both detect staleness and double-close the pool.
+                const stampChanged = !!meta?.indexedAt && meta.indexedAt !== observed;
+                // #2614 F1: also reinit on a file-identity change. An atomic swap (or an
+                // in-place incremental) changes the lbug inode; keying only on
+                // meta.indexedAt let a reader that reinited inside the pre-swap window
+                // latch on the old inode forever (its stamp already == meta.indexedAt).
+                const currentIdentity = await statDbIdentity(repo.lbugPath);
+                const identityChanged = dbIdentityChanged(this.lastObservedDbIdentity.get(poolKey) ?? null, currentIdentity);
+                if (stampChanged || identityChanged) {
+                    // Index was rebuilt/swapped — DELEGATE the close/reopen to the pool's
+                    // initLbug, which refuses to evict (and close the shared Database)
+                    // while a query is in flight (its checkedOut>0 guard). Calling
+                    // closeLbug directly here bypassed that guard and could close a
+                    // Database mid-query — a native use-after-free (#2614). Wrap in
+                    // reinitPromises to serialize concurrent detectors.
                     const reinit = (async () => {
                         try {
-                            await closeLbug(poolKey);
-                            this.initializedRepos.delete(poolKey);
-                            this.lastObservedIndexedAt.set(poolKey, meta.indexedAt);
-                            await initLbug(poolKey, repo.lbugPath);
-                            this.initializedRepos.add(poolKey);
+                            // Advance the observed stamp regardless: a stamp change with an
+                            // unchanged file must not re-trigger on every check.
+                            if (meta?.indexedAt)
+                                this.lastObservedIndexedAt.set(poolKey, meta.indexedAt);
+                            const reopened = await initLbug(poolKey, repo.lbugPath);
+                            // Advance the observed IDENTITY only when the pool actually rolled
+                            // over. If a query was in flight, initLbug served the current
+                            // handle and returned false; leaving the identity divergent
+                            // re-triggers the reopen on a later idle check instead of latching.
+                            if (reopened) {
+                                this.lastObservedDbIdentity.set(poolKey, await statDbIdentity(repo.lbugPath));
+                            }
                         }
                         finally {
                             this.reinitPromises.delete(poolKey);
@@ -1077,6 +1176,7 @@ export class LocalBackend {
             await initLbug(poolKey, repo.lbugPath);
             this.initializedRepos.add(poolKey);
             this.lastObservedIndexedAt.set(poolKey, repo.indexedAt);
+            this.lastObservedDbIdentity.set(poolKey, await statDbIdentity(repo.lbugPath));
         }
         catch (err) {
             // If lock error, mark as not initialized so next call retries
@@ -1278,7 +1378,10 @@ export class LocalBackend {
         if (method.startsWith('group_')) {
             return this.handleGroupTool(method, params || {});
         }
-        const p = params && typeof params === 'object' ? params : {};
+        const normalized = normalizeToolParams(method, params);
+        if ('error' in normalized)
+            return { error: normalized.error };
+        const p = normalized.params;
         // #2175: Claude Code drops a tool-call argument named exactly "query", so the
         // query/cypher tools advertise "search_query"/"statement" while still accepting the
         // legacy "query" key for backward compat. The alias is resolved with `?? ` (new name
@@ -1295,46 +1398,59 @@ export class LocalBackend {
         }
         // Resolve repo from optional param (re-reads registry on miss). An optional
         // `branch` param scopes the resolved handle to that branch's index (#2106).
-        const repoParams = params;
-        const repo = await this.resolveRepo(repoParams?.repo, repoParams?.branch);
+        const repo = await this.resolveRepo(p.repo, p.branch);
         switch (method) {
             case 'query':
-                return this.query(repo, params);
+                return this.query(repo, p);
             case 'cypher': {
-                const raw = await this.cypher(repo, params);
+                const raw = await this.cypher(repo, p);
                 return this.formatCypherAsMarkdown(raw);
             }
             case 'context':
-                return this.context(repo, params);
+                return this.context(repo, p);
             case 'explain':
-                return this.explain(repo, params);
+                return this.explain(repo, p);
             case 'pdg_query':
-                return this.pdgQuery(repo, params);
+                return this.pdgQuery(repo, p);
             case 'impact':
-                return this.impact(repo, params);
+                return this.impact(repo, p);
             case 'detect_changes':
-                return this.detectChanges(repo, params);
+                return this.detectChanges(repo, p);
             case 'check':
-                return this.check(repo, params);
+                return this.check(repo, p);
             case 'rename':
-                return this.rename(repo, params);
+                return this.rename(repo, p);
             // Legacy aliases for backwards compatibility
             case 'search':
-                return this.query(repo, params);
+                return this.query(repo, p);
             case 'explore':
-                return this.context(repo, { name: params?.name, ...params });
+                return this.context(repo, {
+                    name: typeof p.name === 'string' ? p.name : undefined,
+                    ...p,
+                });
             case 'overview':
-                return this.overview(repo, params);
+                return this.overview(repo, p);
             case 'route_map':
-                return this.routeMap(repo, params);
+                return this.routeMap(repo, p);
             case 'shape_check':
-                return this.shapeCheck(repo, params);
+                return this.shapeCheck(repo, p);
             case 'tool_map':
-                return this.toolMap(repo, params);
+                return this.toolMap(repo, p);
             case 'api_impact':
-                return this.apiImpact(repo, params);
+                return this.apiImpact(repo, p);
+            // Move/Aptos tools (graph-property/Cypher only — no move-flow shell-out).
+            case 'move_entries':
+                return this.moveEntries(repo, p);
+            case 'move_resources':
+                return this.moveResources(repo, p);
+            case 'move_impact':
+                return this.moveImpact(repo, {
+                    target: typeof p.target === 'string' ? p.target : '',
+                    direction: p.direction === 'upstream' || p.direction === 'downstream' ? p.direction : undefined,
+                    maxDepth: typeof p.maxDepth === 'number' ? p.maxDepth : undefined,
+                });
             case 'trace':
-                return this.trace(repo, params);
+                return this.trace(repo, p);
             default:
                 throw new Error(`Unknown tool: ${method}`);
         }
@@ -1564,8 +1680,8 @@ export class LocalBackend {
                 name: sym.name,
                 type: sym.type,
                 filePath: sym.filePath,
-                startLine: sym.startLine,
-                endLine: sym.endLine,
+                startLine: toDisplayLine(sym.startLine),
+                endLine: toDisplayLine(sym.endLine),
                 ...(module ? { module } : {}),
                 ...(includeContent && content ? { content } : {}),
             };
@@ -1652,7 +1768,7 @@ export class LocalBackend {
         // path, leaving the success-path response shape byte-identical.
         const warnings = [];
         if (!ftsUsed) {
-            warnings.push('FTS indexes missing — keyword search degraded. Run: gitnexus analyze --repair-fts (or gitnexus analyze --force) to rebuild indexes.');
+            warnings.push(ftsDegradedWarning());
         }
         // #2331: a CJK query against a server process resolving
         // GITNEXUS_FTS_CJK_SEGMENTATION to 'none' silently misses sub-phrase
@@ -1791,8 +1907,11 @@ export class LocalBackend {
                             name: sym.name || sym[1],
                             type: sym.type || sym[2],
                             filePath: sym.filePath || sym[3],
-                            startLine: sym.startLine || sym[4],
-                            endLine: sym.endLine || sym[5],
+                            // Raw 0-based here — `bm25Search` is only called from `query()`,
+                            // whose aggregation loop applies `toDisplayLine` once (see below).
+                            // Converting here too would double-shift BM25-matched lines (#2380).
+                            startLine: sym.startLine ?? sym[4],
+                            endLine: sym.endLine ?? sym[5],
                             bm25Score: bm25Result.score,
                         });
                     }
@@ -1834,10 +1953,16 @@ export class LocalBackend {
             const queryVecStr = `[${queryVec.join(',')}]`;
             const maxDistance = getVectorMaxDistance(DEFAULT_MCP_VECTOR_MAX_DISTANCE);
             let bestChunks = new Map();
-            if (isVectorExtensionSupportedByPlatform()) {
-                try {
-                    bestChunks = await collectBestChunks(limit, async (fetchLimit) => {
-                        const vectorQuery = `
+            // Always TRY the vector lane — no platform gate. LadybugDB ships the
+            // VECTOR extension for every supported platform, Windows included
+            // (#2623 follow-up; the old `platform !== 'win32'` gate was stale), so
+            // whether the index is queryable is a per-machine runtime fact. The
+            // catch below is the fallback: any failure (extension unloadable, index
+            // absent, older DB) degrades to the exact scan with a once-per-backend
+            // diagnostic instead of being silently swallowed.
+            try {
+                bestChunks = await collectBestChunks(limit, async (fetchLimit) => {
+                    const vectorQuery = `
             CALL QUERY_VECTOR_INDEX('${EMBEDDING_TABLE_NAME}', '${EMBEDDING_INDEX_NAME}',
               CAST(${queryVecStr} AS FLOAT[${dims}]), ${fetchLimit})
             YIELD node AS emb, distance
@@ -1847,27 +1972,25 @@ export class LocalBackend {
                    emb.startLine AS startLine, emb.endLine AS endLine, distance
             ORDER BY distance
           `;
-                        const embResults = await executeQuery(repo.lbugPath, vectorQuery);
-                        return embResults.map((row) => ({
-                            nodeId: row.nodeId ?? row[0],
-                            chunkIndex: row.chunkIndex ?? row[1] ?? 0,
-                            startLine: row.startLine ?? row[2] ?? 0,
-                            endLine: row.endLine ?? row[3] ?? 0,
-                            distance: row.distance ?? row[4],
-                        }));
-                    });
-                }
-                catch {
-                    bestChunks = new Map();
-                }
+                    const embResults = await executeQuery(repo.lbugPath, vectorQuery);
+                    return embResults.map((row) => ({
+                        nodeId: row.nodeId ?? row[0],
+                        chunkIndex: row.chunkIndex ?? row[1] ?? 0,
+                        startLine: row.startLine ?? row[2] ?? 0,
+                        endLine: row.endLine ?? row[3] ?? 0,
+                        distance: row.distance ?? row[4],
+                    }));
+                });
             }
-            else if (!this.warnedVectorUnsupported) {
-                // Rare diagnostic: surface why we fell back to the exact scan path so
-                // operators can see at a glance that VECTOR is disabled by platform
-                // policy. Emitted once per `LocalBackend` instance lifetime to avoid
-                // noisy stderr on hot semantic-search paths (DoD §2.8).
-                this.warnedVectorUnsupported = true;
-                logger.warn('GitNexus [query:vector]: VECTOR extension not supported on this platform; using exact scan fallback');
+            catch (err) {
+                bestChunks = new Map();
+                if (!this.warnedVectorUnsupported) {
+                    // Rare diagnostic: surface why semantic search fell back to the
+                    // exact scan. Emitted once per `LocalBackend` instance lifetime to
+                    // avoid noisy stderr on hot semantic-search paths (DoD §2.8).
+                    this.warnedVectorUnsupported = true;
+                    logger.warn({ err }, 'GitNexus [query:vector]: vector index query failed; using exact scan fallback');
+                }
             }
             if (bestChunks.size === 0) {
                 const embeddingCount = Number(tableCheck[0].cnt ?? tableCheck[0][0] ?? 0);
@@ -1927,8 +2050,20 @@ export class LocalBackend {
             }
             return results;
         }
-        catch {
-            // Expected when embeddings are disabled — silently fall back to BM25-only
+        catch (err) {
+            // Embeddings disabled is the common, silent case. But a pruned or
+            // Node-unloadable optional stack (#2370/#2372) also lands here — surface it
+            // once so semantic search doesn't silently degrade to BM25 with no hint
+            // (the exact silent-degradation mode #2370 exists to fix). Emitted once per
+            // LocalBackend instance to keep stderr quiet on hot paths (like the VECTOR
+            // fallback above). All other errors stay silent, as before.
+            const message = err instanceof Error ? err.message : '';
+            if (!this.warnedMissingEmbeddingStack &&
+                (isMissingLocalEmbeddingStackMessage(message) ||
+                    isLocalEmbeddingRuntimeBlockerMessage(message))) {
+                this.warnedMissingEmbeddingStack = true;
+                logger.warn(`GitNexus [query:vector]: ${message}`);
+            }
             return [];
         }
     }
@@ -2376,7 +2511,7 @@ export class LocalBackend {
                     name: c.name,
                     kind: c.type,
                     filePath: c.filePath,
-                    line: c.startLine,
+                    line: toDisplayLine(c.startLine),
                     score: Number(c.score.toFixed(2)),
                 })),
             };
@@ -2540,6 +2675,7 @@ export class LocalBackend {
         // "fix" enrichment ordering; F3 depends on enrichment-before-early-return.
         const epistemicSymType = (resolvedLabel || sym.type || symKind || '');
         const epistemicPromise = this.computeEpistemicBoundary(repo, symId, epistemicSymType, (sym.name || sym[1]));
+        const beanMetadataPromise = queryClassBeanMetadata(repo.lbugPath, symId, epistemicSymType);
         let methodMetadata;
         if (isMethodLike) {
             try {
@@ -2575,7 +2711,7 @@ export class LocalBackend {
         // dynamic dispatch are not reflected in `incoming`, so the view is a lower
         // bound. Additive; never suppresses a field. Resolved from the probe started
         // above (concurrent with methodMetadata).
-        const epistemic = await epistemicPromise;
+        const [epistemic, beanMetadata] = await Promise.all([epistemicPromise, beanMetadataPromise]);
         return {
             status: 'found',
             symbol: {
@@ -2583,10 +2719,11 @@ export class LocalBackend {
                 name: sym.name || sym[1],
                 kind: symKind,
                 filePath: sym.filePath || sym[3],
-                startLine: sym.startLine || sym[4],
-                endLine: sym.endLine || sym[5],
+                startLine: toDisplayLine(sym.startLine ?? sym[4]),
+                endLine: toDisplayLine(sym.endLine ?? sym[5]),
                 ...(include_content && (sym.content || sym[6]) ? { content: sym.content || sym[6] } : {}),
                 ...(methodMetadata ? { methodMetadata } : {}),
+                ...(beanMetadata ? { bean: beanMetadata } : {}),
             },
             ...epistemic,
             incoming: categorize(incomingRows),
@@ -2660,7 +2797,7 @@ export class LocalBackend {
                         name: c.name,
                         kind: c.type,
                         filePath: c.filePath,
-                        line: c.startLine,
+                        line: toDisplayLine(c.startLine),
                         score: Number(c.score.toFixed(2)),
                     })),
                 },
@@ -2678,11 +2815,14 @@ export class LocalBackend {
             return {
                 anchorClause: 'a.id STARTS WITH $idPrefix AND a.startLine >= $symStart AND a.startLine <= $symEnd',
                 queryParams: { idPrefix, symStart: sym.startLine + 1, symEnd: sym.endLine + 1 },
+                // Display anchor is 1-based, matching the ambiguous-candidate branch and
+                // the context/query/impact tools (#2380). This is display-only — the
+                // BasicBlock join above uses the raw `sym.startLine + 1` in `symStart`.
                 anchor: {
                     file: sym.filePath,
                     symbol: sym.name,
-                    startLine: sym.startLine,
-                    endLine: sym.endLine,
+                    startLine: toDisplayLine(sym.startLine),
+                    endLine: toDisplayLine(sym.endLine),
                 },
             };
         }
@@ -3425,7 +3565,10 @@ export class LocalBackend {
         /** Guard: ensure a file path resolves within the repo root (prevents path traversal) */
         const assertSafePath = (filePath) => {
             const full = path.resolve(repo.repoPath, filePath);
-            if (!full.startsWith(repo.repoPath + path.sep) && full !== repo.repoPath) {
+            const safePrefix = repo.repoPath.endsWith(path.sep)
+                ? repo.repoPath
+                : repo.repoPath + path.sep;
+            if (!full.startsWith(safePrefix) && full !== repo.repoPath) {
                 throw new Error(`Path traversal blocked: ${filePath}`);
             }
             return full;
@@ -3447,28 +3590,13 @@ export class LocalBackend {
         if (oldName === new_name) {
             return { error: 'New name is the same as the current name.' };
         }
-        // Step 2: Collect edits from graph (high confidence)
-        const changes = new Map();
-        const addEdit = (filePath, line, oldText, newText, confidence) => {
-            if (!changes.has(filePath)) {
-                changes.set(filePath, { file_path: filePath, edits: [] });
-            }
-            changes.get(filePath).edits.push({ line, old_text: oldText, new_text: newText, confidence });
-        };
-        // The definition itself
-        if (sym.filePath && sym.startLine) {
-            try {
-                const content = await fs.readFile(assertSafePath(sym.filePath), 'utf-8');
-                const lines = content.split('\n');
-                const lineIdx = sym.startLine - 1;
-                if (lineIdx >= 0 && lineIdx < lines.length && lines[lineIdx].includes(oldName)) {
-                    const defRegex = new RegExp(`\\b${oldName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'g');
-                    addEdit(sym.filePath, sym.startLine, lines[lineIdx].trim(), lines[lineIdx].replace(defRegex, new_name).trim(), 'graph');
-                }
-            }
-            catch (e) {
-                logQueryError('rename:read-definition', e);
-            }
+        const escapedOldName = oldName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        // Classify each file to rewrite by how it was discovered. Definition and
+        // graph-ref files carry graph confidence; files found only by text search
+        // carry text_search confidence. A graph-classified file is never downgraded.
+        const fileConfidence = new Map();
+        if (sym.filePath) {
+            fileConfidence.set(sym.filePath, 'graph');
         }
         // All incoming refs from graph (callers, importers, etc.)
         const allIncoming = [
@@ -3477,31 +3605,12 @@ export class LocalBackend {
             ...(lookupResult.incoming.extends || []),
             ...(lookupResult.incoming.implements || []),
         ];
-        let graphEdits = changes.size > 0 ? 1 : 0; // count definition edit
         for (const ref of allIncoming) {
-            if (!ref.filePath)
-                continue;
-            try {
-                const content = await fs.readFile(assertSafePath(ref.filePath), 'utf-8');
-                const lines = content.split('\n');
-                for (let i = 0; i < lines.length; i++) {
-                    if (lines[i].includes(oldName)) {
-                        addEdit(ref.filePath, i + 1, lines[i].trim(), lines[i]
-                            .replace(new RegExp(`\\b${oldName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'g'), new_name)
-                            .trim(), 'graph');
-                        graphEdits++;
-                        break; // one edit per file from graph refs
-                    }
-                }
-            }
-            catch (e) {
-                logQueryError('rename:read-ref', e);
+            if (ref.filePath) {
+                fileConfidence.set(ref.filePath, 'graph');
             }
         }
-        // Step 3: Text search for refs the graph might have missed
-        let astSearchEdits = 0;
-        const graphFiles = new Set([sym.filePath, ...allIncoming.map((r) => r.filePath)].filter(Boolean));
-        // Simple text search across the repo for the old name (in files not already covered by graph)
+        // Text search for files the graph might have missed entirely.
         try {
             const { execFileSync } = await import('child_process');
             const rgArgs = [
@@ -3527,65 +3636,199 @@ export class LocalBackend {
                 .filter((f) => f.length > 0);
             for (const file of files) {
                 const normalizedFile = file.replace(/\\/g, '/').replace(/^\.\//, '');
-                if (graphFiles.has(normalizedFile))
-                    continue; // already covered by graph
-                try {
-                    const content = await fs.readFile(assertSafePath(normalizedFile), 'utf-8');
-                    const lines = content.split('\n');
-                    const regex = new RegExp(`\\b${oldName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'g');
-                    for (let i = 0; i < lines.length; i++) {
-                        regex.lastIndex = 0;
-                        if (regex.test(lines[i])) {
-                            regex.lastIndex = 0;
-                            addEdit(normalizedFile, i + 1, lines[i].trim(), lines[i].replace(regex, new_name).trim(), 'text_search');
-                            astSearchEdits++;
-                        }
-                    }
-                }
-                catch (e) {
-                    logQueryError('rename:text-search-read', e);
+                // Never downgrade a graph-classified file to text_search.
+                if (!fileConfidence.has(normalizedFile)) {
+                    fileConfidence.set(normalizedFile, 'text_search');
                 }
             }
         }
         catch (e) {
             logQueryError('rename:ripgrep', e);
         }
-        // Step 4: Apply or preview
-        const allChanges = Array.from(changes.values());
-        const totalEdits = allChanges.reduce((sum, c) => sum + c.edits.length, 0);
+        // Enumerate every `\boldName\b` line in each file to rewrite, so the previewed
+        // file set is exactly the set the apply loop below rewrites. A file with no
+        // matching line is dropped (apply would write nothing to it). `wordTest`
+        // (non-global) probes each line; `wordReplace` (global) rewrites it and is
+        // reused by the apply loop — compiled once each rather than once per line,
+        // and one escaping formula serves both passes.
+        const wordTest = new RegExp(`\\b${escapedOldName}\\b`);
+        const wordReplace = new RegExp(`\\b${escapedOldName}\\b`, 'g');
+        const changes = new Map();
+        for (const [filePath, confidence] of fileConfidence) {
+            try {
+                const content = await fs.readFile(assertSafePath(filePath), 'utf-8');
+                const lines = content.split('\n');
+                const edits = [];
+                for (let i = 0; i < lines.length; i++) {
+                    if (!wordTest.test(lines[i])) {
+                        continue;
+                    }
+                    edits.push({
+                        line: i + 1,
+                        old_text: lines[i].trim(),
+                        new_text: lines[i].replace(wordReplace, new_name).trim(),
+                        confidence,
+                    });
+                }
+                if (edits.length > 0) {
+                    changes.set(filePath, { file_path: filePath, edits });
+                }
+            }
+            catch (e) {
+                logQueryError('rename:enumerate', e);
+            }
+        }
+        // Step 4: Apply or preview.
         const failedFiles = [];
         if (!dry_run) {
-            // Apply edits to files
-            for (const change of allChanges) {
+            for (const change of changes.values()) {
                 try {
                     const fullPath = assertSafePath(change.file_path);
-                    let content = await fs.readFile(fullPath, 'utf-8');
-                    const regex = new RegExp(`\\b${oldName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'g');
-                    content = content.replace(regex, new_name);
-                    await fs.writeFile(fullPath, content, 'utf-8');
+                    const content = await fs.readFile(fullPath, 'utf-8');
+                    await fs.writeFile(fullPath, content.replace(wordReplace, new_name), 'utf-8');
                 }
                 catch (e) {
-                    // A swallowed write failure must not be reported as a full success
-                    // (#2283): record the file so the result can degrade to 'partial'
-                    // with the unwritten files listed, rather than masquerading as done.
+                    // A swallowed write failure must not be reported as success (#2283):
+                    // record the file so the result degrades to 'partial'.
                     logQueryError('rename:apply-edit', e);
                     failedFiles.push(change.file_path);
                 }
             }
+            // A file whose write threw did not land, so drop its edits from the
+            // reported result — total_edits/changes must describe what actually
+            // reached disk, not what was attempted (#2605: the report matches reality
+            // even on partial failure). failed_files still names every dropped file.
+            for (const f of failedFiles) {
+                changes.delete(f);
+            }
+        }
+        // Counts derive from the reported set (dry-run: every enumerated file;
+        // apply: only files that landed), so the graph/text_search split always
+        // sums to total_edits and never overstates a partial apply.
+        const reported = Array.from(changes.values());
+        let graphEdits = 0;
+        let astSearchEdits = 0;
+        for (const change of reported) {
+            for (const edit of change.edits) {
+                if (edit.confidence === 'graph') {
+                    graphEdits++;
+                }
+                else {
+                    astSearchEdits++;
+                }
+            }
         }
         return {
             status: failedFiles.length > 0 ? 'partial' : 'success',
             old_name: oldName,
             new_name,
-            files_affected: allChanges.length,
-            total_edits: totalEdits,
+            files_affected: reported.length,
+            total_edits: graphEdits + astSearchEdits,
             graph_edits: graphEdits,
             text_search_edits: astSearchEdits,
-            changes: allChanges,
+            changes: reported,
             applied: !dry_run,
             ...(failedFiles.length > 0 && { failed_files: failedFiles }),
         };
     }
+    async moveEntries(repo, params) {
+        await this.ensureInitialized(repo);
+        if (!isLbugReady(repo.lbugPath))
+            return { error: 'LadybugDB not ready. Index may be corrupted.' };
+        const clauses = ["f.language = 'move'"];
+        switch (params?.kind) {
+            case 'entry':
+                clauses.push('f.isEntry = true');
+                break;
+            case 'view':
+                clauses.push('f.isView = true');
+                break;
+            case 'inline':
+                clauses.push('f.isInline = true');
+                break;
+            case 'native':
+                clauses.push('f.isNative = true');
+                break;
+            default:
+                clauses.push('(f.isEntry = true OR f.isView = true)');
+        }
+        const qp = {};
+        if (typeof params?.module === 'string' && params.module) {
+            clauses.push('f.moduleQualifiedName = $module');
+            qp.module = params.module;
+        }
+        const rows = (await executeParameterized(repo.lbugPath, `MATCH (f:Function) WHERE ${clauses.join(' AND ')}
+       RETURN f.name AS name, f.qualifiedName AS qualifiedName, f.filePath AS filePath,
+              f.isEntry AS isEntry, f.isView AS isView,
+              f.isInline AS isInline, f.isNative AS isNative, f.visibility AS visibility,
+              f.acquires AS acquires, f.attributes AS attributes, f.returnType AS returnType
+       ORDER BY f.filePath, f.name`, qp));
+        const attribute = params?.attribute;
+        const filtered = typeof attribute === 'string' && attribute
+            ? rows.filter((r) => Array.isArray(r.attributes) && r.attributes.includes(attribute))
+            : rows;
+        return { entries: filtered, count: filtered.length };
+    }
+    async moveResources(repo, params) {
+        await this.ensureInitialized(repo);
+        if (!isLbugReady(repo.lbugPath))
+            return { error: 'LadybugDB not ready. Index may be corrupted.' };
+        const qp = {};
+        let moduleFilter = '';
+        if (typeof params?.module === 'string' && params.module) {
+            moduleFilter = ' AND s.moduleQualifiedName = $module';
+            qp.module = params.module;
+        }
+        const resourceQuery = (label) => `
+       MATCH (s:\`${label}\`) WHERE s.language = 'move' AND s.isResource = true${moduleFilter}
+       RETURN s.name AS name, s.qualifiedName AS qualifiedName, s.filePath AS filePath,
+              s.abilities AS abilities, s.fieldList AS fieldList
+       ORDER BY s.qualifiedName`;
+        const accessorQuery = (label) => `
+       MATCH (f:Function)-[r:CodeRelation]->(s:\`${label}\`)
+       WHERE s.language = 'move' AND s.isResource = true${moduleFilter}
+         AND (r.type = 'READS_RESOURCE' OR r.type = 'WRITES_RESOURCE' OR r.type = 'ACQUIRES')
+       RETURN s.qualifiedName AS resourceQualifiedName, f.qualifiedName AS caller,
+              r.type AS reason, f.isEntry AS isEntry, f.isView AS isView`;
+        const [structs, enums, structAccessors, enumAccessors] = await Promise.all([
+            executeParameterized(repo.lbugPath, resourceQuery('Struct'), qp),
+            executeParameterized(repo.lbugPath, resourceQuery('Enum'), qp),
+            executeParameterized(repo.lbugPath, accessorQuery('Struct'), qp),
+            executeParameterized(repo.lbugPath, accessorQuery('Enum'), qp),
+        ]);
+        const rows = [...structs, ...enums].sort((a, b) => String(a.qualifiedName).localeCompare(String(b.qualifiedName)));
+        const accessorsByResource = new Map();
+        for (const row of [...structAccessors, ...enumAccessors]) {
+            const resourceQualifiedName = String(row.resourceQualifiedName ?? '');
+            if (!resourceQualifiedName || !row.caller)
+                continue;
+            const accessors = accessorsByResource.get(resourceQualifiedName) ?? [];
+            accessors.push({
+                caller: row.caller,
+                reason: row.reason,
+                isEntry: row.isEntry,
+                isView: row.isView,
+            });
+            accessorsByResource.set(resourceQualifiedName, accessors);
+        }
+        const resources = rows.map((r) => ({
+            ...r,
+            fieldList: Array.isArray(r.fieldList)
+                ? r.fieldList.map((v) => String(v).replace(/^['"]|['"]$/g, ''))
+                : r.fieldList,
+            accessors: accessorsByResource.get(String(r.qualifiedName)) ?? [],
+        }));
+        return { resources, count: resources.length };
+    }
+    async moveImpact(repo, params) {
+        const impactParams = {
+            target: params.target,
+            direction: params.direction ?? 'upstream',
+            maxDepth: params.maxDepth,
+            relationTypes: ['CALLS', 'READS_RESOURCE', 'WRITES_RESOURCE', 'ACQUIRES', 'USES_TYPE'],
+        };
+        return this.impact(repo, impactParams);
+    }
     async trace(repo, params) {
         try {
             return await this._traceImpl(repo, params);
@@ -4016,7 +4259,7 @@ export class LocalBackend {
                         name: c.name,
                         kind: c.type,
                         filePath: c.filePath,
-                        line: c.startLine,
+                        line: toDisplayLine(c.startLine),
                         score: Number(c.score.toFixed(2)),
                     })),
                 };
@@ -4069,7 +4312,7 @@ export class LocalBackend {
                     name: c.name,
                     kind: c.type,
                     filePath: c.filePath,
-                    line: c.startLine,
+                    line: toDisplayLine(c.startLine),
                     score: Number(c.score.toFixed(2)),
                     impactedCount: summary?.impactedCount ?? 0,
                     risk: summary?.risk ?? 'UNKNOWN',
@@ -4462,6 +4705,9 @@ export class LocalBackend {
         const epistemicPromise = opts.skipEpistemic
             ? Promise.resolve({})
             : this.computeEpistemicBoundary(repo, symId, symType, (sym.name || sym[1]));
+        const beanMetadataPromise = opts.skipEpistemic || summaryOnly
+            ? Promise.resolve(undefined)
+            : queryClassBeanMetadata(repo.lbugPath, symId, symType);
         const impacted = [];
         const visited = new Set([symId]);
         const pdgBridgeEvidenceById = new Map();
@@ -4864,13 +5110,14 @@ export class LocalBackend {
         }
         // #1858 — await the epistemic boundary probe kicked off alongside the BFS
         // above. Additive: leaves impactedCount and every existing field untouched.
-        const epistemic = await epistemicPromise;
+        const [epistemic, beanMetadata] = await Promise.all([epistemicPromise, beanMetadataPromise]);
         const base = {
             target: {
                 id: symId,
                 name: sym.name || sym[1],
                 type: symType,
                 filePath: sym.filePath || sym[2],
+                ...(beanMetadata ? { bean: beanMetadata } : {}),
             },
             direction,
             impactedCount: impacted.length,