weavatrix 0.2.3 → 0.2.4

package/README.md

@@ -111,10 +111,19 @@ An agent skill with recipes ships in [skill/SKILL.md](skill/SKILL.md) — instal
 compile-only edges (Rust module/use, Java imports) are reported separately where that distinction
 changes the result.
 
-Every current edge also carries versioned provenance: `EXTRACTED`, `RESOLVED`, or `INFERRED` today,
-with `EXACT_LSP` and `CONFLICT` reserved for the optional precision overlay. `graph_stats` reports
-the complete breakdown; provenance describes how the relationship was established, while the older
-`confidence` field remains for compatibility.
+Every current edge carries versioned provenance. The parser emits `EXTRACTED`, `RESOLVED`, and
+`INFERRED`; the built-in bounded TypeScript/JavaScript precision overlay upgrades only references
+confirmed by its bundled `typescript-language-server` + TypeScript runtime to `EXACT_LSP`.
+`CONFLICT` means evidence disagrees. `graph_stats` reports the provenance breakdown and the semantic
+provider's `COMPLETE`, `PARTIAL`, `UNAVAILABLE`, or `OFF` state; `OFF` means precision was explicitly
+disabled and only static evidence is active. Java and Rust language-server providers are not bundled
+in 0.2.4: their edges never become `EXACT_LSP`, even when a mixed repository reports a complete
+TypeScript/JavaScript overlay.
+
+The bounded JS/TS provider is enabled by default for new graphs. Set `WEAVATRIX_PRECISION=off`
+before starting the MCP server for parser-only operation from the first build, or pass
+`precision:"off"` to `rebuild_graph` / `open_repo`. The MCPB installer exposes the same `lsp` / `off`
+choice as **TypeScript/JavaScript semantic precision**.
 
 **search / source** — `search_code` (ripgrep-backed, pure-Node fallback), `read_source` (a
 symbol's actual code in one hop), `list_endpoints` (HTTP route inventory:
@@ -159,8 +168,10 @@ in the per-user cache and never need to be committed to Git.
 
 `query_graph` accepts optional `seed_files` when an architectural question must start from exact
 entry points. Resolved explicit seeds are exclusive by default; set `augment_seeds:true` only when
-fuzzy question-derived seeds are also wanted. Broad bootstrap/routing/authentication questions
-without explicit seeds rank conventional entry points and high-level modules ahead of incidental matches.
+question-derived seeds are also wanted. Broad bootstrap/tool-execution/routing questions now rank
+conventional executables and graph-declared production entry points ahead of site, documentation, benchmark
+and fixture matches. Broad ranking remains orientation evidence; use `seed_files` when the intended
+entry point is already known.
 
 **advisories** *(network, explicit opt-in)* — `refresh_advisories`
 
@@ -173,6 +184,40 @@ disclosed instead of silently guessed; and the server **hot-reloads its watched
 modules and catalog** when those files change — other MCP helpers and analysis engines require a
 reconnect.
 
+### 0.2.4 graph-mode correctness and semantic precision patch
+
+- `graph_diff base_ref=...` builds the immutable baseline in the current graph mode, so a
+  `no-tests` graph is never compared with a hidden `full` universe. Previous-rebuild snapshots with
+  mismatched modes are rejected instead of reporting false removals or cycle drift.
+- `trace_api_contract` preserves each registered repository's build mode during refresh and exposes
+  that mode in `graphReconciliation`.
+- `graph_stats` and `open_repo` expose the canonical graph path and build mode; an explicit mode
+  mismatch with `build:false` fails closed instead of silently retargeting.
+- `module_map` is production-only by default and can opt back into classified tests, fixtures,
+  benchmarks, generated output and docs with `include_non_product:true`.
+- A bundled, read-only TypeScript/JavaScript language server validates a bounded set of semantic
+  references after graph reconciliation. Confirmed edges become `EXACT_LSP`; zero-reference evidence
+  can strengthen an internal dead-code candidate only after a successful exact query. Partial,
+  unavailable and revision-mismatched overlays stay visible and never become cosmetic exactness.
+  The provider is Weavatrix's pinned `typescript-language-server` + TypeScript runtime, never a
+  repository binary or `npx` download. Automatic type acquisition is disabled. Its child environment
+  is reduced to OS/temp/locale basics with a Node/System path; registry, proxy, cloud, token and
+  `NODE_OPTIONS` values are not inherited. TypeScript may still read locally declared project
+  configuration, dependencies and type declarations; Weavatrix accepts returned evidence only after
+  repository realpath containment. Applicable config chains are audited before provider startup;
+  configured language-service plugins and unresolved/outside config are refused, while semantic
+  inputs are fingerprinted before cache reuse and rechecked after each run. No source or evidence is
+  transmitted, and the provider performs no Weavatrix HTTP request. MCP EOF/SIGTERM drains or
+  tree-terminates TLS and tsserver before the stdio process exits.
+- Broad `query_graph` bootstrap and tool-execution ranking now prefers production executables and
+  graph-declared entry points over site, docs, benchmark and fixture surfaces. Exact `seed_files` remain
+  the deterministic option when the caller already knows the entry point.
+- The bundled skill routes orientation, diff review, cross-repository API tracing and exact-symbol
+  work through Weavatrix's own evidence states. Java/Rust exact providers remain `UNAVAILABLE` in
+  this release instead of being presented as compiler-confirmed.
+
+Full patch notes: [docs/releases/v0.2.4.md](docs/releases/v0.2.4.md).
+
 ### 0.2.3 real-wrapper patch
 
 - Auto-discovery recognizes wrappers that pass a fixed HTTP client method and argument array to a
@@ -379,9 +424,9 @@ vulnerability findings. This is where each capability comes from and how it is c
 | Capability alert | Why it exists | Activation and boundary |
 |---|---|---|
 | Network access | `refresh_advisories` sends pinned package names and versions to OSV; `pull_architecture_contract` sends an opaque repository UUID and receives an owner-approved contract; `sync_graph` sends a normalized repository label plus an allowlisted graph/evidence payload. Evidence is derived locally from source and manifests, but source bodies, snippets, absolute paths, environment values, credentials and Git remotes are excluded | `offline` and `pinned` expose no network tools. `osv` exposes only advisory refresh. `hosted`/`full` expose all three; every request still requires an explicit tool call, and hosted calls require `WEAVATRIX_SYNC_URL` |
-| Shell access | Local `git` powers staleness/change impact; `rg` accelerates search; timed-out Windows child processes may be terminated | Used only by the corresponding local operation; it does not imply network access |
+| Shell access | Local `git` powers staleness/change impact; `rg` accelerates search; the bundled TLS/tsserver process supplies bounded JS/TS semantic evidence; timed-out Windows child trees may be terminated | Used only by the corresponding local operation. The semantic provider is package-pinned, disables automatic type acquisition, and never invokes a repository binary, script, installer or `npx` |
 | Debug / dynamic loading | Cache-busted `import()` hot-reloads watched MCP tool entry modules; `createRequire` loads package metadata and parser dependencies | Loads files from the installed package; no `eval` |
-| Environment access | Reads `WEAVATRIX_*` configuration; local child processes inherit the normal host environment | `WEAVATRIX_SYNC_TOKEN` is removed from every child-process and worker environment and read only by `sync_graph` / `pull_architecture_contract` |
+| Environment access | Reads `WEAVATRIX_*` configuration; ordinary local helpers inherit a credential-stripped environment, while TLS/tsserver receives only allowlisted OS/temp/locale values and a constrained executable path | `WEAVATRIX_SYNC_TOKEN` is removed from every child-process and worker environment. TLS/tsserver also receives no registry/proxy/cloud credentials or `NODE_OPTIONS` |
 | Filesystem access | Reads the active repository, graph, lockfiles and coverage reports; writes derived graphs and advisory/architecture caches | Realpath containment blocks traversal and symlink/junction escapes. The `pinned` profile removes `open_repo`; the default `offline` profile permits only explicit local switching. The optional malware dependency scan may inspect installed dependency caches such as GOPATH |
 | URL strings | Fixed OSV/documentation URLs plus a user-configured sync URL | A URL string causes no request by itself; only the three network-profile tools perform requests |
 
@@ -435,9 +480,9 @@ loader) behind the thin stdio entry `src/mcp-server.mjs`.
   [app.weavatrix.com](https://app.weavatrix.com): explicit source-free sync,
   immutable history, Flow/DSM/Map, target architecture and bounded review
   evidence. Hosted use remains optional and owner-authenticated.
-- **Semantic precision bridge** — optional local language-server validation for
-  ambiguous impact, reference and dead-code evidence; the current parser graph
-  remains the offline fallback.
+- **Semantic precision bridge** shipped for TypeScript/JavaScript in 0.2.4: a bounded, revision-bound
+  local overlay validates references with the bundled language server while the parser graph remains
+  the fallback. Java and Rust providers are not bundled yet and stay explicitly `UNAVAILABLE`.
 - **Git-native architecture history** — bounded tag/ref timelines and branch
   reports built outside the worktree; graph artifacts stay out of Git.
 - **Cross-repository company evidence** — endpoints, events and internal

package/SECURITY.md

@@ -28,6 +28,24 @@ dependency caches such as GOPATH. `offline` permits repository switching only th
 local `open_repo` call; select `pinned` to remove that tool, the global repository listing, and
 cross-repository API tracing, holding a hard startup-repository boundary.
 
+The JS/TS precision overlay is enabled by default for new graphs and runs the package-pinned `typescript-language-server` and
+TypeScript runtime as local child processes. It never resolves a repository executable, invokes
+`npx`, runs package scripts, or installs dependencies. Automatic type acquisition is disabled, and
+the provider receives an allowlisted OS/temp/locale environment with a constrained executable path;
+registry, proxy, cloud, token and `NODE_OPTIONS` values are excluded. The provider makes no
+Weavatrix HTTP request and Weavatrix transmits no source or evidence. TypeScript may still read
+locally declared project configuration, dependencies and type declarations; returned evidence is
+accepted only after repository realpath containment. Before spawning the provider, Weavatrix parses
+the applicable repo-contained TypeScript/JavaScript config chains with its bundled TypeScript API and
+refuses semantic mode when a configured language-service plugin, unresolved/outside config, or input
+safety limit is encountered. Config and configured-project inputs are fingerprinted and rechecked
+before cached evidence is used and after each provider run.
+This is an application/process boundary rather than an operating-system
+network sandbox. On stdio EOF, SIGTERM or SIGINT, the MCP server stops new providers, performs a
+bounded graph-work drain, and closes or tree-terminates TLS/tsserver before exiting.
+Set `WEAVATRIX_PRECISION=off` before server startup (or select `off` in the MCPB semantic-precision
+setting) to keep new graphs parser-only from their first build.
+
 Network capabilities are split by purpose. `osv` adds only `refresh_advisories`, which sends pinned
 package names and versions to OSV.dev when called. `hosted` / `full` also expose `sync_graph` and
 `pull_architecture_contract`; both require a user-configured endpoint, and contract pull requires

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "weavatrix",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "type": "module",
   "description": "Weavatrix — code graph & blast-radius MCP server for AI coding agents: change impact, transitive dependents, health audit, duplicate detection, and coverage mapping over any local repository.",
   "author": "Sergii Ziborov <sergii.ziborov@gmail.com>",
@@ -55,6 +55,8 @@
   ],
   "dependencies": {
     "tree-sitter-wasms": "0.1.13",
+    "typescript": "5.9.3",
+    "typescript-language-server": "4.4.1",
     "web-tree-sitter": "0.25.10"
   },
   "devDependencies": {

package/skill/SKILL.md

@@ -29,6 +29,28 @@ Profiles use the same npm package and binary:
 The legacy `online` capability remains a compatibility alias for `advisories,hosted`; prefer the
 named profiles for new registrations.
 
+## Intent router
+
+Start from the task, not from the complete tool list:
+
+- **Orient in a repository**: `graph_stats` -> verify `Repo`, `Graph`, and `Build mode`; if the target
+  is wrong, call `open_repo`, then `graph_stats` again -> `module_map` (production-only by default).
+- **Review a branch/diff**: `change_impact` for changed-file blast radius; add
+  `graph_diff base_ref=<merge-base>` for structural drift, then drill into exact candidates with
+  `get_dependents` and `read_source`.
+- **Trace an API across repositories**: `list_known_repos` -> `trace_api_contract` with an explicit
+  backend and client list; inspect each `graphReconciliation.buildMode` before using the verdict.
+- **Inspect exact symbol references**: start with `graph_stats` and read semantic precision state,
+  provider and `EXACT_LSP` count. For TypeScript/JavaScript, use an exact node id with
+  `get_dependents` and inspect the edge provenance; use `find_dead_code` for bounded zero-reference
+  candidates. Treat `PARTIAL`, `UNAVAILABLE`, `OFF`, or zero exact edges as incomplete evidence, not
+  a compiler-exact result; `OFF` means the caller explicitly selected static-only mode. Java and Rust
+  providers are not bundled in 0.2.4, so their edges never become `EXACT_LSP` even when a mixed
+  repository has a complete TypeScript/JavaScript overlay.
+- **Explore an architectural question**: use broad `query_graph` when entry points are unknown; its
+  bootstrap/tool-execution ranking prefers production executables over docs, sites and fixtures.
+  Pass exact `seed_files` when the intended entry points are already known.
+
 ## Ground rules
 
 - **Evidence, not verdicts**: treat audit, hub, orphan and duplicate output as hypotheses. Confirm a
@@ -47,11 +69,12 @@ named profiles for new registrations.
   `change_impact` and `graph_diff` label the distinction; `god_nodes` ranks unique connectivity and
   reports repeated references separately. Do not schedule a runtime-cycle refactor from
   compile-time-only edges.
-- **Edge provenance**: distinguish how an edge was established from legacy confidence. Current
-  graphs use `EXTRACTED`, `RESOLVED`, and `INFERRED`; `EXACT_LSP` is reserved for a bounded local
-  precision overlay and `CONFLICT` means evidence disagrees. Treat `INFERRED` and `CONFLICT` as
-  review signals rather than compiler-exact facts; an `UNKNOWN` count in `graph_stats` requires a
-  rebuild before precision-sensitive work.
+- **Edge provenance**: distinguish how an edge was established from legacy confidence. The parser
+  emits `EXTRACTED`, `RESOLVED`, and `INFERRED`; the bundled bounded TypeScript/JavaScript language
+  server emits `EXACT_LSP` only for references it confirms. `CONFLICT` means evidence disagrees.
+  Treat `INFERRED`, `CONFLICT`, `PARTIAL`, `UNAVAILABLE`, and `OFF` as review signals rather than
+  compiler-exact facts; an `UNKNOWN` count or revision-mismatched overlay in `graph_stats` requires
+  a rebuild before precision-sensitive work.
 - **Repository universe**: in Git repositories, graph and duplicate scans include tracked plus
   non-ignored untracked files. If an old graph still contains packaged/generated output, rebuild it
   before interpreting the result. Repository-root `.weavatrixignore` applies the same tracked-file
@@ -60,9 +83,10 @@ named profiles for new registrations.
   roots. Dead-code/clone/audit review also suppresses `benchmarks/**` and `**/__temp/**` as classified
   non-production surfaces. A verified production benchmark can opt back in narrowly through
   `.weavatrix.json` `classify.product`, for example `{"classify":{"product":["benchmarks/core/**"]}}`.
-- **Architectural queries**: for bootstrap/routing/authentication questions, inspect the returned
-  seeds before trusting the traversal. Pass exact repository-relative `seed_files` to `query_graph`
-  when the intended entry points are already known.
+- **Architectural queries**: broad bootstrap/tool-execution/routing questions rank conventional
+  production and graph-declared entry points ahead of classified docs, sites, benchmarks and
+  fixtures. Inspect the returned seeds before trusting the traversal. Pass exact repository-relative
+  `seed_files` to `query_graph` when the intended entry points are already known.
 - **Coverage**: `coverage_map` reads an existing report. `unavailable` means no supported report was
   found, not 0% coverage; do not rank testing risk from that state.
 - **Audit completeness**: read `checks.osv.status` and `checks.malware.status`. For OSV, `OK` is
@@ -71,8 +95,10 @@ named profiles for new registrations.
   the same non-`OK` states as incomplete for malware scanning. Refresh OSV only when the user has
   authorized selecting the optional `osv` profile (or `advisories` capability) and then
   invoking `refresh_advisories`; enabling the group alone sends nothing.
-- **Offline by design**: scans and graph queries run in-process against local files; coverage tools
-  read existing reports and never run tests. The ONLY network-touching tools live in the optional
+- **Offline by design**: scans and graph queries use local files; the semantic overlay may launch
+  Weavatrix's bundled read-only TypeScript language-server child process, but it never runs repository
+  scripts or downloads a provider. Coverage tools read existing reports and never run tests. The
+  ONLY network-touching tools live in the optional
   `advisories` / `hosted` capabilities and run solely when explicitly called:
   `refresh_advisories` (queries OSV.dev with
   package names + versions so `run_audit` has fresh vulnerability data) and `sync_graph` (derives a

package/src/analysis/dead-code-review.js

@@ -50,10 +50,18 @@ function symbolCandidate(item, node, context) {
   const dynamicFile = context.dynamicTargets.has(file) || DYNAMIC_RE.test(source);
   const reflectionFile = REFLECTION_RE.test(source);
   const kind = kindOf(node);
-  let confidence = (String(node?.visibility || "").toLowerCase() === "private" || (!publicSurface && ["method", "function"].includes(kind)))
-    ? "high" : "medium";
+  const exactNoReference = context.exactNoReferenceIds.has(String(item.id));
+  const internallyScoped = String(node?.visibility || "").toLowerCase() === "private"
+    || (!publicSurface && ["method", "function"].includes(kind));
+  // Static absence alone is never high-confidence dead code. High is reserved for a successfully
+  // queried semantic declaration whose language server also returned no in-workspace references.
+  let confidence = internallyScoped && exactNoReference ? "high" : "medium";
   const caveats = [];
 
+  if (internallyScoped && !exactNoReference) {
+    caveats.push("No complete exact semantic no-reference result is available for this declaration; static absence remains medium confidence.");
+  }
+
   if (publicSurface) {
     confidence = "low";
     caveats.push("Public/exported APIs can be consumed by downstream packages, interfaces, reflection, dependency injection, templates, or configuration outside this repository.");
@@ -90,6 +98,7 @@ function symbolCandidate(item, node, context) {
     evidence: [
       { kind: "graph", fact: "No inbound non-structural graph edge targets this symbol." },
       { kind: "source-index", fact: "Its identifier has no second indexed occurrence that establishes a caller." },
+      ...(exactNoReference ? [{kind: "exact-lsp", fact: "The active language server returned no in-workspace references for this exact declaration."}] : []),
     ],
     caveats,
     publicApi: publicSurface,
@@ -169,7 +178,8 @@ export function computeDeadCodeReview(graph, sources, options = {}) {
   const minConfidence = Object.hasOwn(CONFIDENCE_RANK, options.minConfidence) ? options.minConfidence : "medium";
   const pathPrefix = normalizedPath(options.path || "").replace(/\/+$/, "");
   const requestedKinds = new Set(Array.isArray(options.kinds) && options.kinds.length ? options.kinds : ["file", "function", "method", "symbol"]);
-  const context = { sources, entrySet, dynamicTargets, frameworkByFile, classify, repoSignals };
+  const exactNoReferenceIds = new Set(graph.precisionNoReferenceSymbols || options.exactNoReferenceIds || []);
+  const context = { sources, entrySet, dynamicTargets, frameworkByFile, classify, repoSignals, exactNoReferenceIds };
   const dead = computeDead(graph, sources, { entrySet });
   const nodesById = new Map((graph.nodes || []).map((node) => [String(node.id), node]));
   const rawSymbols = dead.deadSymbols

package/src/analysis/git-ref-graph.js

@@ -7,6 +7,7 @@ import {tmpdir} from 'node:os'
 import {spawnSync} from 'node:child_process'
 import {childProcessEnv} from '../child-env.js'
 import {buildInternalGraph} from '../graph/internal-builder.js'
+import {filterGraphForMode} from '../graph/graph-filter.js'
 
 const SAFE_REF = /^(?!-)[A-Za-z0-9][A-Za-z0-9._\/@{}+~^-]{0,199}$/
 
@@ -68,7 +69,14 @@ export async function withGitRefCheckout(repoRoot, requestedRef, operation) {
     }
 }
 
-export async function buildGraphAtGitRef(repoRoot, requestedRef) {
-    const result = await withGitRefCheckout(repoRoot, requestedRef, async (checkout) => buildInternalGraph(checkout))
+export async function buildGraphAtGitRef(repoRoot, requestedRef, {mode = 'full'} = {}) {
+    const buildMode = ['full', 'no-tests', 'tests-only'].includes(mode) ? mode : 'full'
+    const result = await withGitRefCheckout(repoRoot, requestedRef, async (checkout) => {
+        const fullGraph = await buildInternalGraph(checkout)
+        return {
+            ...filterGraphForMode(fullGraph, buildMode, {repoRoot: checkout}),
+            graphBuildMode: buildMode,
+        }
+    })
     return result.ok ? {...result, graph: result.value} : result
 }

package/src/build-graph.js

@@ -14,7 +14,8 @@ import { graphHomeDir, graphOutDirForRepo, graphStorageKey, repoTopFolders, summ
 import { registerRepository } from "./graph/repo-registry.js";
 import { refreshGraphIncrementally, snapshotRepository } from "./graph/incremental-refresh.js";
 import { atomicWriteFileSync, withFileLock } from "./graph/file-lock.js";
-import { repositoryFreshnessProbe, stampRepositoryFreshness } from "./graph/freshness-probe.js";
+import { graphSchemaIsCurrent, repositoryFreshnessProbe, stampRepositoryFreshness } from "./graph/freshness-probe.js";
+import { buildLspPrecisionOverlay, invalidatePrecisionOverlay, precisionSummary } from "./precision/lsp-overlay.js";
 
 // The worker path deadlocks web-tree-sitter's WASM in Electron's worker threads (fine in plain Node) — off
 // until that's Electron-safe. In-process + event-loop yielding keeps the window responsive without it.
@@ -26,6 +27,10 @@ const USE_BUILD_WORKER = false;
 // freeze the whole app on the main thread). 4 min is generous for very large repos.
 const BUILD_WORKER_TIMEOUT_MS = 4 * 60 * 1000;
 
+export function defaultPrecisionMode(env = process.env) {
+  return env?.WEAVATRIX_PRECISION === "off" ? "off" : "lsp";
+}
+
 function buildGraphInWorker(payload) {
   return new Promise((resolve, reject) => {
     let worker;
@@ -56,7 +61,7 @@ function buildGraphInWorker(payload) {
   });
 }
 
-async function buildAndWriteInProcess(repoPath, { mode, scope, graphJson, central }) {
+async function buildAndWriteInProcess(repoPath, { mode, scope, precision, graphJson, central }) {
   const { buildInternalGraph } = await import("./graph/internal-builder.js");
   // Capture the cheap Git state on both sides of the authoritative build. Only an unchanged pair is
   // safe to persist: if the working tree moves while parsing, the next process must take the slow path.
@@ -66,7 +71,7 @@ async function buildAndWriteInProcess(repoPath, { mode, scope, graphJson, centra
   if (mode === "full" && !scope && existsSync(graphJson)) {
     try {
       const existing = JSON.parse(readFileSync(graphJson, "utf8"));
-      if (existing.graphBuildMode === "full" && !existing.graphBuildScope) {
+      if (existing.graphBuildMode === "full" && !existing.graphBuildScope && graphSchemaIsCurrent(existing)) {
         refresh = await refreshGraphIncrementally(repoPath, existing, { buildGraph: buildInternalGraph });
         graph = refresh.graph;
       }
@@ -75,7 +80,7 @@ async function buildAndWriteInProcess(repoPath, { mode, scope, graphJson, centra
   if (!graph && mode !== "full" && !scope && existsSync(graphJson)) {
     try {
       const existing = JSON.parse(readFileSync(graphJson, "utf8"));
-      if (existing.graphBuildMode === mode && existing.graphRevision) {
+      if (existing.graphBuildMode === mode && existing.graphRevision && graphSchemaIsCurrent(existing)) {
         const snapshot = snapshotRepository(repoPath);
         if (snapshot.revision === existing.graphRevision) {
           graph = existing;
@@ -93,6 +98,9 @@ async function buildAndWriteInProcess(repoPath, { mode, scope, graphJson, centra
   if (scope) graph = filterGraphByScope(graph, scope);
   graph.graphBuildMode = mode;
   graph.graphBuildScope = scope || "";
+  const requestedPrecision = precision === "off" ? "off" : "lsp";
+  const precisionModeChanged = graph.graphPrecisionMode !== requestedPrecision;
+  graph.graphPrecisionMode = requestedPrecision;
   const probeAfter = scope ? null : repositoryFreshnessProbe(repoPath);
   const stableProbe = probeBefore && probeAfter === probeBefore ? probeAfter : null;
   const freshnessMetadataChanged = stampRepositoryFreshness(graph, stableProbe, mode);
@@ -100,20 +108,50 @@ async function buildAndWriteInProcess(repoPath, { mode, scope, graphJson, centra
   // multi-megabyte graph merely to answer that nothing changed (or manufacture a newer mtime).
   // A one-time metadata-only write is intentional for legacy graphs so the next MCP process can use
   // the persisted probe instead of repeating a full repository snapshot.
-  if (refresh?.kind !== "none" || freshnessMetadataChanged) {
+  if (refresh?.kind !== "none" || freshnessMetadataChanged || precisionModeChanged) {
     mkdirSync(central, { recursive: true });
     atomicWriteFileSync(graphJson, JSON.stringify(graph), "utf8");
   }
+  mkdirSync(central, { recursive: true });
+  let precisionOverlay = await buildLspPrecisionOverlay({
+    repoRoot: repoPath,
+    graph,
+    graphPath: graphJson,
+    mode: requestedPrecision,
+  });
+  if (requestedPrecision === "lsp") {
+    try {
+      // LSP deliberately runs after graph serialization and can outlive the initial snapshot. A
+      // complete second content snapshot catches source/config add-delete races (including Git
+      // assume-unchanged paths) that a status-only token cannot prove away.
+      if (snapshotRepository(repoPath).revision !== graph.graphRevision) {
+        precisionOverlay = invalidatePrecisionOverlay(graphJson, graph);
+      }
+    } catch {
+      precisionOverlay = invalidatePrecisionOverlay(
+        graphJson,
+        graph,
+        "repository freshness could not be verified after semantic precision",
+      );
+    }
+  }
   return {
     nodes: graph.nodes.length,
     links: graph.links.length,
     communities: summarizeCommunities(graphJson),
     hotspots: summarizeHotspots(graphJson),
     refresh,
+    precision: precisionSummary(precisionOverlay),
   };
 }
 
-export async function buildGraphForRepo(repoPath, { mode = "full", scope = "", outDir, graphHome } = {}) {
+export async function buildGraphForRepo(repoPath, {
+  mode = "full",
+  scope = "",
+  precision = defaultPrecisionMode(),
+  outDir,
+  graphHome,
+} = {}) {
   if (!existsSync(repoPath)) return { ok: false, error: "Repo path not found", builder: "internal" };
   const registryHome = graphHome || graphHomeDir();
   const canonicalDir = graphHome ? join(registryHome, graphStorageKey(repoPath)) : graphOutDirForRepo(repoPath);
@@ -126,11 +164,11 @@ export async function buildGraphForRepo(repoPath, { mode = "full", scope = "", o
     // between file chunks, so the main-thread parse no longer freezes the window — the reason the worker was
     // introduced. buildGraphInWorker/USE_BUILD_WORKER are kept for a future Electron-safe re-enable.
     const build = () => USE_BUILD_WORKER
-      ? buildGraphInWorker({ repoPath, mode, scope, graphJson, central }).catch((e) => {
-          if (e && e.workerStartFailed) return buildAndWriteInProcess(repoPath, { mode, scope, graphJson, central });
+      ? buildGraphInWorker({ repoPath, mode, scope, precision, graphJson, central }).catch((e) => {
+          if (e && e.workerStartFailed) return buildAndWriteInProcess(repoPath, { mode, scope, precision, graphJson, central });
           throw e;
         })
-      : buildAndWriteInProcess(repoPath, { mode, scope, graphJson, central });
+      : buildAndWriteInProcess(repoPath, { mode, scope, precision, graphJson, central });
     // Canonical graphs are shared by all local MCP clients. Serialize the complete read/refresh/write
     // transaction so an older process cannot overwrite a newer incremental result.
     const canonical = !scope && resolve(central) === resolve(canonicalDir);
@@ -154,7 +192,8 @@ export async function buildGraphForRepo(repoPath, { mode = "full", scope = "", o
       communities: built.communities,
       hotspots: built.hotspots,
       refresh: built.refresh,
-      log: `built-in builder: ${built.nodes} nodes, ${built.links} links (${built.refresh?.kind || "full"}: ${built.refresh?.reason || "build"})`
+      precision: built.precision,
+      log: `built-in builder: ${built.nodes} nodes, ${built.links} static links (${built.refresh?.kind || "full"}: ${built.refresh?.reason || "build"}); semantic precision ${built.precision?.state || "UNAVAILABLE"}, ${built.precision?.verifiedEdges || 0} EXACT_LSP edge(s)`
     };
   } catch (error) {
     return { ok: false, error: `graph build failed: ${error.message}`, builder: "internal" };

package/src/graph/build-worker.js

@@ -8,20 +8,40 @@ import { parentPort, workerData } from "node:worker_threads";
 import { buildInternalGraph } from "./internal-builder.js";
 import { filterGraphForMode, filterGraphByScope, summarizeCommunities, summarizeHotspots } from "./layout.js";
 import { atomicWriteFileSync } from "./file-lock.js";
+import { snapshotRepository } from "./incremental-refresh.js";
+import { buildLspPrecisionOverlay, invalidatePrecisionOverlay, precisionSummary } from "../precision/lsp-overlay.js";
 
 (async () => {
-  const { repoPath, mode, scope, graphJson, central } = workerData || {};
+  const { repoPath, mode, scope, precision, graphJson, central } = workerData || {};
   try {
     let graph = await buildInternalGraph(repoPath);
     if (mode === "no-tests" || mode === "tests-only") graph = filterGraphForMode(graph, mode, { repoRoot: repoPath });
     if (scope) graph = filterGraphByScope(graph, scope);
+    graph.graphBuildMode = mode;
+    graph.graphBuildScope = scope || "";
+    graph.graphPrecisionMode = precision === "off" ? "off" : "lsp";
     atomicWriteFileSync(graphJson, JSON.stringify(graph), "utf8");
+    let overlay = await buildLspPrecisionOverlay({repoRoot: repoPath, graph, graphPath: graphJson, mode: graph.graphPrecisionMode});
+    if (graph.graphPrecisionMode === "lsp") {
+      try {
+        if (snapshotRepository(repoPath).revision !== graph.graphRevision) {
+          overlay = invalidatePrecisionOverlay(graphJson, graph);
+        }
+      } catch {
+        overlay = invalidatePrecisionOverlay(
+          graphJson,
+          graph,
+          "repository freshness could not be verified after semantic precision",
+        );
+      }
+    }
     parentPort.postMessage({
       ok: true,
       nodes: graph.nodes.length,
       links: graph.links.length,
       communities: summarizeCommunities(graphJson),
       hotspots: summarizeHotspots(graphJson),
+      precision: precisionSummary(overlay),
     });
   } catch (e) {
     parentPort.postMessage({ ok: false, error: (e && e.message) || String(e) });

package/src/graph/builder/lang-java.js

@@ -83,6 +83,7 @@ export default {
       const id = nodeIds.has(base) ? `${base}:c${nameNode.startPosition.column + 1}` : base;
       addSym(nameNode.text, lineOf(nameNode), callable, {
         ...extra,
+        selectionNode: nameNode,
         ...(id === base ? {} : { idSuffix: id.slice(base.length) }),
       });
       return nodeIds.has(id) ? id : null;

package/src/graph/builder/lang-js.js

@@ -93,6 +93,7 @@ export default {
       const exportStatement = !isMethod && exportStatementOf(cap.node);
       addSym(cap.node.text, cap.node.startPosition.row + 1, cap.name !== "class", {
         sourceNode: cap.node.parent,
+        selectionNode: cap.node,
         ...(exportStatement ? { exported: true } : {}),
         ...(isMethod ? methodMetadata(cap.node) : { symbolKind: cap.name === "class" ? "class" : "function", moduleDeclaration: isModuleDeclaration(cap.node) })
       });
@@ -111,6 +112,7 @@ export default {
       const exported = isExportedDecl(cap.node);
       addSym(nameNode.text, nameNode.startPosition.row + 1, !!(val && CALLABLE.test(val.type)), {
         sourceNode: val || cap.node,
+        selectionNode: nameNode,
         ...(exported ? { exported: true } : {}),
         symbolKind: "variable",
         moduleDeclaration: true

package/src/graph/freshness-probe.js

@@ -9,7 +9,7 @@ import {childProcessEnv} from '../child-env.js'
 import {createRepoBoundary} from '../repo-path.js'
 
 export const REPOSITORY_FRESHNESS_PROBE_V = 1
-export const GRAPH_BUILDER_SCHEMA_V = 2
+export const GRAPH_BUILDER_SCHEMA_V = 3
 export const GRAPH_BUILDER_VERSION = (() => {
     try { return String(createRequire(import.meta.url)('../../package.json').version) }
     catch { return '0.0.0' }
@@ -25,7 +25,7 @@ const CURRENT_GRAPH_SCHEMA = Object.freeze({
     complexityV: 1,
     repoBoundaryV: 1,
     barrelResolutionV: 1,
-    extractorSchemaV: 1,
+    extractorSchemaV: 3,
 })
 const CONTROL_FILES = ['.gitignore', '.weavatrixignore', '.weavatrix.json']
 const MAX_CONTROL_BYTES = 1_000_000

package/src/graph/incremental-refresh.js

@@ -183,7 +183,7 @@ export async function refreshGraphIncrementally(repoDir, existingGraph, {
 
   if (!existingGraph || !existingGraph.fileHashes || !existingGraph.fileExportSignatures
     || !existingGraph.controlHashes || !existingGraph.jsExportRecords || Number(existingGraph.barrelResolutionV) < 1
-    || Number(existingGraph.extractorSchemaV) < 1 || Number(existingGraph.edgeProvenanceV) < 1) {
+    || Number(existingGraph.extractorSchemaV) < 3 || Number(existingGraph.edgeProvenanceV) < 1) {
     return full("incremental-baseline-unavailable");
   }
   if (!sameRecord(existingGraph.controlHashes, snapshot.controlHashes)) return full("ignore-or-control-config-changed");

package/src/graph/internal-builder.build.js

@@ -89,6 +89,7 @@ export async function buildInternalGraph(repoDir, opts = {}) {
       const suffix = /^:[A-Za-z0-9_-]+$/.test(extra?.idSuffix || "") ? extra.idSuffix : "";
       const id = `${fileRel}#${name}@${line}${suffix}`; if (nodeIds.has(id)) return;
       const sourceNode = extra && extra.sourceNode;
+      const selectionNode = extra && extra.selectionNode;
       const endLine = sourceNode?.endPosition ? sourceNode.endPosition.row + 1 : 0;
       let complexity = null;
       if (callable && sourceNode) {
@@ -98,10 +99,38 @@ export async function buildInternalGraph(repoDir, opts = {}) {
       addNode({
         id,
         label: callable ? `${name}()` : name,
+        ...(callable ? { callable: true } : {}),
         file_type: "code",
         source_file: fileRel,
         source_location: `L${line}`,
         ...(endLine >= line ? { source_end: `L${endLine}` } : {}),
+        ...(sourceNode?.startPosition && sourceNode?.endPosition ? {
+          // web-tree-sitter Point columns are zero-based UTF-16 code-unit offsets. Keep the
+          // declaration body range as well as the identifier selection so LSP reference
+          // locations on a boundary line cannot be attributed to the wrong symbol.
+          source_range: {
+            start: {
+              line: sourceNode.startPosition.row,
+              character: sourceNode.startPosition.column,
+            },
+            end: {
+              line: sourceNode.endPosition.row,
+              character: sourceNode.endPosition.column,
+            },
+          },
+        } : {}),
+        ...(selectionNode?.startPosition && selectionNode?.endPosition ? {
+          // web-tree-sitter's JavaScript Point columns are already zero-based UTF-16 code-unit
+          // offsets, matching LSP positions exactly (including text before non-ASCII identifiers).
+          selection_start: {
+            line: selectionNode.startPosition.row,
+            character: selectionNode.startPosition.column,
+          },
+          selection_end: {
+            line: selectionNode.endPosition.row,
+            character: selectionNode.endPosition.column,
+          },
+        } : {}),
         ...(complexity ? { complexity } : {}),
         ...(extra && extra.exported ? { exported: true } : {}),
         ...(extra && extra.decorated ? { decorated: true } : {}),
@@ -217,7 +246,7 @@ export async function buildInternalGraph(repoDir, opts = {}) {
     for (const cap of caps(grammar, lang.calls, tree.rootNode)) {
       const caller = enclosing(fileRel, cap.node.startPosition.row + 1); if (!caller) continue;
       const target = resolveCall(cap.node.text, fileRel); if (!target || target === caller.id) continue;
-      links.push({ source: caller.id, target, relation: "calls", confidence: "INFERRED" });
+      links.push({ source: caller.id, target, relation: "calls", confidence: "INFERRED", line: cap.node.startPosition.row + 1 });
     }
     // qualified/selector calls (Go): `pkg.Func()` → the imported package's dir; else `receiver.Method()` → the
     // SAME package (heuristic by method name — connects lifecycle methods like peer.Enable() that need type info).
@@ -229,7 +258,7 @@ export async function buildInternalGraph(repoDir, opts = {}) {
       const dir = fileRel.includes("/") ? fileRel.slice(0, fileRel.lastIndexOf("/")) : "";
       const dm = goDirSymbols.get(imp && imp.targetDir ? imp.targetDir : dir);
       const target = dm && dm.get(fld.text);
-      if (target && target !== caller.id) links.push({ source: caller.id, target, relation: "calls", confidence: "INFERRED" });
+      if (target && target !== caller.id) links.push({ source: caller.id, target, relation: "calls", confidence: "INFERRED", line: cap.node.startPosition.row + 1 });
     }
     for (const heritageSpec of lang.heritage || []) {
       const query = typeof heritageSpec === "string" ? heritageSpec : heritageSpec.query;
@@ -253,7 +282,7 @@ export async function buildInternalGraph(repoDir, opts = {}) {
         if (origin.status !== "resolved") continue;
         const target = symByFileName.get(origin.origin.file)?.get(origin.origin.name);
         const caller = enclosing(fileRel, cap.node.startPosition.row + 1);
-        if (target && caller && target !== caller.id) links.push({ source: caller.id, target, relation: "calls", confidence: "INFERRED" });
+        if (target && caller && target !== caller.id) links.push({ source: caller.id, target, relation: "calls", confidence: "INFERRED", line: cap.node.startPosition.row + 1 });
       }
       for (const cap of caps(grammar, `[
         (jsx_opening_element name: (_) @jsx)
@@ -335,7 +364,7 @@ export async function buildInternalGraph(repoDir, opts = {}) {
     complexityV: 1,
     repoBoundaryV: 1,
     barrelResolutionV: 1,
-    extractorSchemaV: 1,
+    extractorSchemaV: 3,
     jsExportRecords: Object.fromEntries([...jsExports.entries()].sort(([a], [b]) => a.localeCompare(b))),
     fileHashes: snapshot.fileHashes,
     fileExportSignatures: snapshot.fileExportSignatures,