weavatrix 0.1.1 → 0.1.3

package/src/mcp/graph-context.mjs

@@ -5,7 +5,9 @@
 import {readFileSync, statSync} from 'node:fs'
 import {join} from 'node:path'
 import {spawnSync} from 'node:child_process'
+import {childProcessEnv} from '../child-env.js'
 import {buildFileImportGraph, findSccs} from '../analysis/dep-rules.js'
+import {resolveRepoPath} from '../repo-path.js'
 
 // ---- graph load + indexes -----------------------------------------------------------------------
 export function loadGraph(path) {
@@ -31,10 +33,21 @@ export function loadGraph(path) {
         if (!e || e.source == null || e.target == null) continue
         const s = String(e.source)
         const t = String(e.target)
-        push(out, s, {id: t, relation: e.relation, confidence: e.confidence})
-        push(inn, t, {id: s, relation: e.relation, confidence: e.confidence})
+        const metadata = {
+            relation: e.relation,
+            confidence: e.confidence,
+            ...(e.typeOnly === true ? {typeOnly: true} : {}),
+            ...(Number.isInteger(e.line) ? {line: e.line} : {}),
+            ...(typeof e.specifier === 'string' ? {specifier: e.specifier} : {}),
+        }
+        push(out, s, {id: t, ...metadata})
+        push(inn, t, {id: s, ...metadata})
+    }
+    return {
+        nodes, links, byId, byLabel, out, inn,
+        repoBoundaryV: Number(raw.repoBoundaryV) || 0,
+        edgeTypesV: Number(raw.edgeTypesV) || 0,
     }
-    return {nodes, links, byId, byLabel, out, inn}
 }
 
 export const isSymbol = (id) => String(id).includes('#')
@@ -47,6 +60,7 @@ export const labelOf = (g, id) => {
 // "connectivity" degree ignores structural `contains` (parent→symbol nesting) so god_nodes surfaces real
 // call/import/reference hubs, not just files that hold many symbols.
 export const connList = (list) => (list || []).filter((e) => e.relation !== 'contains')
+export const uniqueConnCount = (list) => new Set(connList(list).map((e) => String(e.id))).size
 
 // Resolve a user-supplied "label" to a node: exact id → exact label → ci label → substring (best degree).
 // Returns {node, matches, alternates} so callers can disclose ambiguity instead of silently picking one.
@@ -123,13 +137,13 @@ export function graphStaleness(ctx) {
     try { info.builtAt = statSync(ctx.graphPath).mtime } catch { /* no graph file — nothing to report */ }
     if (ctx.repoRoot && info.builtAt) {
         try {
-            const head = spawnSync('git', ['-C', ctx.repoRoot, 'log', '-1', '--format=%cI'], {encoding: 'utf8', timeout: 4000})
+            const head = spawnSync('git', ['-C', ctx.repoRoot, 'log', '-1', '--format=%cI'], {encoding: 'utf8', timeout: 4000, env: childProcessEnv()})
             const iso = (head.stdout || '').trim()
             if (head.status === 0 && iso) {
                 info.headAt = new Date(iso)
                 if (info.headAt > info.builtAt) {
                     info.stale = true
-                    const cnt = spawnSync('git', ['-C', ctx.repoRoot, 'rev-list', '--count', `--since=${info.builtAt.toISOString()}`, 'HEAD'], {encoding: 'utf8', timeout: 4000})
+                    const cnt = spawnSync('git', ['-C', ctx.repoRoot, 'rev-list', '--count', `--since=${info.builtAt.toISOString()}`, 'HEAD'], {encoding: 'utf8', timeout: 4000, env: childProcessEnv()})
                     if (cnt.status === 0) info.behind = Number(cnt.stdout.trim()) || null
                 }
             }
@@ -138,7 +152,7 @@ export function graphStaleness(ctx) {
         // they edit, then re-query). Count dirty files actually TOUCHED after the build — a dirty file
         // older than the graph was already part of it.
         try {
-            const st = spawnSync('git', ['-C', ctx.repoRoot, 'status', '--porcelain'], {encoding: 'utf8', timeout: 4000})
+            const st = spawnSync('git', ['-C', ctx.repoRoot, 'status', '--porcelain'], {encoding: 'utf8', timeout: 4000, env: childProcessEnv()})
             if (st.status === 0) {
                 let newer = 0
                 for (const ln of String(st.stdout || '').split(/\r?\n/).filter(Boolean).slice(0, 200)) {
@@ -170,7 +184,8 @@ export function fileStalenessNote(ctx, sourceFile) {
     const s = graphStaleness(ctx)
     if (!s.builtAt) return null
     try {
-        if (statSync(join(ctx.repoRoot, String(sourceFile))).mtime > s.builtAt) {
+        const resolved = resolveRepoPath(ctx.repoRoot, String(sourceFile))
+        if (resolved.ok && statSync(resolved.path).mtime > s.builtAt) {
             return `Note: ${sourceFile} changed after the graph was built — line numbers above may have drifted (rebuild_graph refreshes them).`
         }
     } catch { /* file gone — the read tools will surface that themselves */ }
@@ -203,27 +218,43 @@ const folderOfFile = (file) => {
 
 // Works on anything with {nodes, links}: the raw graph.json shape and the loadGraph struct alike.
 export function diffGraphs(oldG, newG) {
+    const oldEdgeTypesV = Number(oldG.edgeTypesV) || 0
+    const newEdgeTypesV = Number(newG.edgeTypesV) || 0
+    const schemaMigration = oldEdgeTypesV !== newEdgeTypesV
     const nodeIds = (graph) => new Set((graph.nodes || []).map((n) => String(n.id)))
     const oldNodes = nodeIds(oldG)
     const newNodes = nodeIds(newG)
 
-    const edgeKey = (l) => `${edgeEndpoint(l.source)}|${l.relation || ''}|${edgeEndpoint(l.target)}`
+    const edgeKey = (l) => `${edgeEndpoint(l.source)}|${l.relation || ''}|${schemaMigration ? 'untyped' : l.typeOnly === true ? 'type' : 'runtime'}|${edgeEndpoint(l.target)}`
     const edgeSet = (graph) => new Set((graph.links || []).map(edgeKey))
     const oldEdges = edgeSet(oldG)
     const newEdges = edgeSet(newG)
 
-    const moduleEdges = (graph) => {
+    const moduleEdges = (graph, typeOnly) => {
         const set = new Set()
         for (const l of graph.links || []) {
             if (l.relation === 'contains') continue
+            if ((l.typeOnly === true) !== typeOnly) continue
             const a = folderOfFile(fileOfId(edgeEndpoint(l.source)))
             const b = folderOfFile(fileOfId(edgeEndpoint(l.target)))
             if (a !== b) set.add(`${a} → ${b}`)
         }
         return set
     }
-    const oldMods = moduleEdges(oldG)
-    const newMods = moduleEdges(newG)
+    const combinedModuleEdges = (graph) => {
+        const set = new Set()
+        for (const l of graph.links || []) {
+            if (l.relation === 'contains') continue
+            const a = folderOfFile(fileOfId(edgeEndpoint(l.source)))
+            const b = folderOfFile(fileOfId(edgeEndpoint(l.target)))
+            if (a !== b) set.add(`${a} → ${b}`)
+        }
+        return set
+    }
+    const oldMods = schemaMigration ? combinedModuleEdges(oldG) : moduleEdges(oldG, false)
+    const newMods = schemaMigration ? combinedModuleEdges(newG) : moduleEdges(newG, false)
+    const oldTypeMods = schemaMigration ? new Set() : moduleEdges(oldG, true)
+    const newTypeMods = schemaMigration ? new Set() : moduleEdges(newG, true)
 
     const incoming = (graph) => {
         const m = new Map()
@@ -237,9 +268,47 @@ export function diffGraphs(oldG, newG) {
     const oldIn = incoming(oldG)
     const newIn = incoming(newG)
 
-    const cycles = (graph) => { try { return findSccs(buildFileImportGraph(graph).adj).length } catch { return null } }
+    const cycles = (graph, includeTypeOnly) => {
+        try {
+            const sccs = findSccs(buildFileImportGraph(graph, {includeTypeOnly}).adj)
+                .map((members) => members.map(String).sort())
+                .sort((a, b) => b.length - a.length || a.join('\n').localeCompare(b.join('\n')))
+            return {
+                count: sccs.length,
+                largest: sccs[0]?.length || 0,
+                groups: sccs,
+            }
+        } catch {
+            return null
+        }
+    }
+    const cycleDelta = (before, after) => {
+        if (!before || !after) return null
+        const key = (group) => group.join('|')
+        const beforeKeys = new Set(before.groups.map(key))
+        const afterKeys = new Set(after.groups.map(key))
+        const overlap = (a, b) => {
+            const bSet = new Set(b)
+            return a.reduce((n, member) => n + (bSet.has(member) ? 1 : 0), 0)
+        }
+        const unmatchedBefore = before.groups.filter((group) => !afterKeys.has(key(group)))
+        const unmatchedAfter = after.groups.filter((group) => !beforeKeys.has(key(group)))
+        const changed = unmatchedAfter.filter((group) => unmatchedBefore.some((old) => overlap(group, old) >= 2))
+        const introduced = unmatchedAfter.filter((group) => !unmatchedBefore.some((old) => overlap(group, old) >= 2))
+        const resolved = unmatchedBefore.filter((group) => !unmatchedAfter.some((next) => overlap(group, next) >= 2))
+        return {
+            before: before.count,
+            after: after.count,
+            largestBefore: before.largest,
+            largestAfter: after.largest,
+            introduced: introduced.map(key),
+            resolved: resolved.map(key),
+            membershipChanged: changed.length,
+        }
+    }
 
     return {
+        schemaMigration: schemaMigration ? {from: oldEdgeTypesV, to: newEdgeTypesV} : null,
         nodes: {
             added: [...newNodes].filter((id) => !oldNodes.has(id)),
             removed: [...oldNodes].filter((id) => !newNodes.has(id))
@@ -250,25 +319,46 @@ export function diffGraphs(oldG, newG) {
         },
         moduleEdges: {
             added: [...newMods].filter((k) => !oldMods.has(k)),
-            removed: [...oldMods].filter((k) => !newMods.has(k))
+            removed: [...oldMods].filter((k) => !newMods.has(k)),
+            typeAdded: [...newTypeMods].filter((k) => !oldTypeMods.has(k)),
+            typeRemoved: [...oldTypeMods].filter((k) => !newTypeMods.has(k)),
         },
         // survived the rebuild but lost every caller/importer — likely made dead by the change
         orphaned: [...oldIn.keys()].filter((id) => newNodes.has(id) && !newIn.has(id)),
-        cycles: {before: cycles(oldG), after: cycles(newG)}
+        cycles: {
+            runtime: schemaMigration ? null : cycleDelta(cycles(oldG, false), cycles(newG, false)),
+            typeInclusive: schemaMigration ? null : cycleDelta(cycles(oldG, true), cycles(newG, true)),
+        }
     }
 }
 
 export function formatGraphDiff(d) {
     if (!d.nodes.added.length && !d.nodes.removed.length && !d.edges.added && !d.edges.removed) {
-        return 'No structural change between the two graph states.'
+        return d.schemaMigration
+            ? `Graph edge schema upgraded v${d.schemaMigration.from} → v${d.schemaMigration.to}; typed baseline established. Runtime/type cycle and module classifications are intentionally not compared on this rebuild.`
+            : 'No structural change between the two graph states.'
     }
     const cap = (list, n) => list.slice(0, n).map((x) => `  ${x}`).concat(list.length > n ? [`  … +${list.length - n} more`] : [])
     const lines = [`Structural delta: nodes +${d.nodes.added.length}/−${d.nodes.removed.length}, edges +${d.edges.added}/−${d.edges.removed}.`]
-    if (d.cycles.before != null && d.cycles.after != null && d.cycles.before !== d.cycles.after) {
-        lines.push(`Import cycles: ${d.cycles.before} → ${d.cycles.after}${d.cycles.after < d.cycles.before ? '  (cycle broken — fix confirmed)' : '  (NEW cycle introduced — see run_audit)'}`)
+    if (d.schemaMigration) lines.push(`Graph edge schema upgraded v${d.schemaMigration.from} → v${d.schemaMigration.to}; runtime/type cycle and module classifications are intentionally not compared until the next rebuild.`)
+    const runtime = d.cycles?.runtime
+    if (runtime && (runtime.before !== runtime.after || runtime.largestBefore !== runtime.largestAfter || runtime.introduced.length || runtime.resolved.length || runtime.membershipChanged)) {
+        const changes = []
+        if (runtime.introduced.length) changes.push(`${runtime.introduced.length} genuinely new runtime SCC(s) — review`)
+        if (runtime.resolved.length) changes.push(`${runtime.resolved.length} runtime SCC(s) resolved`)
+        if (runtime.membershipChanged) changes.push(`${runtime.membershipChanged} SCC membership change(s)`)
+        const verdict = changes.length ? `; ${changes.join('; ')}` : ''
+        lines.push(`Runtime import cycles: count ${runtime.before} → ${runtime.after}, largest SCC ${runtime.largestBefore} → ${runtime.largestAfter}${verdict}.`)
+    }
+    const all = d.cycles?.typeInclusive
+    if (all && (all.before !== all.after || all.largestBefore !== all.largestAfter) &&
+        (!runtime || all.before !== runtime.before || all.after !== runtime.after || all.largestBefore !== runtime.largestBefore || all.largestAfter !== runtime.largestAfter)) {
+        lines.push(`Type-inclusive dependency SCCs: count ${all.before} → ${all.after}, largest ${all.largestBefore} → ${all.largestAfter} (compile-time coupling, not necessarily a runtime cycle).`)
     }
     if (d.moduleEdges.added.length) lines.push('NEW module dependencies (architecture drift — review):', ...cap(d.moduleEdges.added, 12))
     if (d.moduleEdges.removed.length) lines.push('Removed module dependencies (decoupling confirmed):', ...cap(d.moduleEdges.removed, 12))
+    if (d.moduleEdges.typeAdded.length) lines.push('New type-only module dependencies (compile-time coupling):', ...cap(d.moduleEdges.typeAdded, 12))
+    if (d.moduleEdges.typeRemoved.length) lines.push('Removed type-only module dependencies:', ...cap(d.moduleEdges.typeRemoved, 12))
     if (d.orphaned.length) lines.push('Symbols that lost their last caller/importer (now dead?):', ...cap(d.orphaned, 10))
     if (d.nodes.added.length) lines.push('Added nodes:', ...cap(d.nodes.added, 12))
     if (d.nodes.removed.length) lines.push('Removed nodes:', ...cap(d.nodes.removed, 12))

package/src/mcp/sync-payload.mjs

@@ -0,0 +1,110 @@
+// Versioned, explicit wire schema for sync_graph. Never forward graph.json wholesale: it is a local
+// cache file and may contain future fields or attacker-injected data that are not safe to upload.
+
+const CONTROL_CHARS = /[\u0000-\u001f\u007f]/;
+
+function metadataString(value, max = 4096) {
+    return typeof value === 'string' && value.length > 0 && value.length <= max && !CONTROL_CHARS.test(value)
+        ? value
+        : undefined;
+}
+
+function finiteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+function setIf(out, key, value) {
+    if (value !== undefined) out[key] = value;
+}
+
+const COMPLEXITY_NUMBERS = [
+    'startLine', 'endLine', 'loc', 'params', 'objectFields', 'branches', 'cyclomatic',
+    'loops', 'maxLoopDepth', 'returns', 'awaits', 'callCount', 'externalCalls',
+    'asyncBoundaries', 'allocations', 'objectLiterals', 'spreadCopies', 'sorts',
+    'linearOps', 'timeRank', 'timeScore', 'memoryRank', 'memoryScore',
+];
+
+function sanitizeComplexity(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+    const out = {};
+    for (const key of COMPLEXITY_NUMBERS) setIf(out, key, finiteNumber(value[key]));
+    if (typeof value.recursion === 'boolean') out.recursion = value.recursion;
+    for (const key of ['family', 'scope', 'complexityScope', 'confidence']) {
+        setIf(out, key, metadataString(value[key], 32));
+    }
+    return Object.keys(out).length ? out : undefined;
+}
+
+function sanitizeNode(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+    const id = metadataString(value.id);
+    if (!id) return null;
+    const out = {id};
+    setIf(out, 'label', metadataString(value.label, 1024));
+    setIf(out, 'file_type', metadataString(value.file_type, 32));
+    setIf(out, 'source_file', metadataString(value.source_file));
+    const sourceLocation = metadataString(value.source_location, 32);
+    const sourceEnd = metadataString(value.source_end, 32);
+    if (sourceLocation && /^L\d+$/.test(sourceLocation)) out.source_location = sourceLocation;
+    if (sourceEnd && /^L\d+$/.test(sourceEnd)) out.source_end = sourceEnd;
+    const community = finiteNumber(value.community);
+    if (community !== undefined && Number.isInteger(community) && community >= 0) out.community = community;
+    if (typeof value.exported === 'boolean') out.exported = value.exported;
+    if (typeof value.decorated === 'boolean') out.decorated = value.decorated;
+    setIf(out, 'complexity', sanitizeComplexity(value.complexity));
+    return out;
+}
+
+function sanitizeLink(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+    const source = metadataString(value.source);
+    const target = metadataString(value.target);
+    if (!source || !target) return null;
+    const out = {source, target};
+    setIf(out, 'relation', metadataString(value.relation, 32));
+    setIf(out, 'confidence', metadataString(value.confidence, 32));
+    if (value.typeOnly === true) out.typeOnly = true;
+    const line = finiteNumber(value.line);
+    if (line !== undefined && Number.isInteger(line) && line >= 0) out.line = line;
+    setIf(out, 'specifier', metadataString(value.specifier));
+    return out;
+}
+
+function sanitizeExternalImport(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+    const file = metadataString(value.file);
+    if (!file) return null;
+    const out = {file};
+    for (const key of ['spec', 'target']) setIf(out, key, metadataString(value[key]));
+    for (const key of ['pkg', 'kind', 'ecosystem']) setIf(out, key, metadataString(value[key], 256));
+    const line = finiteNumber(value.line);
+    if (line !== undefined && Number.isInteger(line) && line >= 0) out.line = line;
+    for (const key of ['builtin', 'dynamic', 'unresolved']) {
+        if (typeof value[key] === 'boolean') out[key] = value[key];
+    }
+    return out;
+}
+
+export function createSyncPayload(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw) || raw.repoBoundaryV !== 1) {
+        throw new Error('graph predates repository-boundary hardening');
+    }
+    if (!Number.isInteger(raw.edgeTypesV) || raw.edgeTypesV < 1) {
+        throw new Error('graph predates typed import edges');
+    }
+    const nodes = Array.isArray(raw.nodes) ? raw.nodes.map(sanitizeNode).filter(Boolean) : [];
+    const links = Array.isArray(raw.links) ? raw.links.map(sanitizeLink).filter(Boolean) : [];
+    const externalImports = Array.isArray(raw.externalImports)
+        ? raw.externalImports.map(sanitizeExternalImport).filter(Boolean)
+        : [];
+    return {
+        syncPayloadV: 2,
+        repoBoundaryV: 1,
+        edgeTypesV: 1,
+        extImportsV: Number.isInteger(raw.extImportsV) ? raw.extImportsV : 0,
+        complexityV: Number.isInteger(raw.complexityV) ? raw.complexityV : 0,
+        nodes,
+        links,
+        externalImports,
+    };
+}

package/src/mcp/tools-actions.mjs

@@ -1,13 +1,14 @@
-// Action tools: rebuild the graph, retarget the server at another repo, list sibling repos with
-// built graphs — plus the 'online' capability group (the ONLY tools that ever touch the network).
+// Action tools: rebuild the graph, the explicit 'retarget' group, and the explicit 'online' group
+// (the ONLY tools that ever touch the network).
 // Hot-reloadable (re-imported by catalog.mjs on change).
-import {readFileSync, writeFileSync, existsSync, readdirSync, statSync} from 'node:fs'
-import {join, dirname} from 'node:path'
+import {readFileSync, writeFileSync, existsSync, readdirSync, statSync, realpathSync} from 'node:fs'
+import {join, dirname, isAbsolute} from 'node:path'
 import {prevGraphPathFor, diffGraphs, formatGraphDiff} from './graph-context.mjs'
 import {buildGraphForRepo} from '../build-graph.js'
 import {graphOutDirForRepo} from '../graph/layout.js'
 import {refreshAdvisories, storeMeta, DEFAULT_STORE} from '../security/advisory-store.js'
 import {collectInstalled} from '../security/installed.js'
+import {createSyncPayload} from './sync-payload.mjs'
 
 export async function tRebuildGraph(g, args, ctx) {
     if (!ctx.repoRoot) return 'Rebuild needs the repo root (not provided to this server).'
@@ -15,7 +16,7 @@ export async function tRebuildGraph(g, args, ctx) {
     // snapshot the outgoing state: bytes → graph.prev.json (for graph_diff later), struct → inline delta
     let prevBytes = null
     try { prevBytes = readFileSync(ctx.graphPath) } catch { /* first build — nothing to diff against */ }
-    const before = g?.nodes ? {nodes: g.nodes, links: g.links} : null
+    const before = g?.nodes ? {nodes: g.nodes, links: g.links, edgeTypesV: g.edgeTypesV || 0} : null
     const res = await buildGraphForRepo(ctx.repoRoot, {mode, scope: args.scope || ''})
     if (!res || !res.ok) return `Graph rebuild failed: ${(res && res.error) || 'unknown error'}`
     if (prevBytes) { try { writeFileSync(prevGraphPathFor(ctx.graphPath), prevBytes) } catch { /* snapshot is best-effort */ } }
@@ -31,13 +32,30 @@ export async function tRebuildGraph(g, args, ctx) {
 // repo. Loads <parent>/weavatrix-graphs/<name>/graph.json (the central layout graphs
 // always live in), building it first when missing. On a failed load the previous repo stays active.
 export async function tOpenRepo(g, args, ctx) {
-    const repoPath = String(args.path || '').trim().replace(/[\\/]+$/, '')
-    if (!repoPath) return 'Provide "path" — an absolute path to a local repository folder.'
-    if (!existsSync(repoPath)) return `Path not found: ${repoPath}`
+    const requestedPath = String(args.path || '').trim()
+    if (!requestedPath) return 'Provide "path" — an absolute path to a local repository folder.'
+    if (!isAbsolute(requestedPath)) return 'open_repo requires an absolute repository path.'
+    let repoPath
+    try { repoPath = realpathSync.native(requestedPath) } catch { return `Path not found: ${requestedPath}` }
+    try { if (!statSync(repoPath).isDirectory()) return `Not a directory: ${requestedPath}` } catch { return `Path not found: ${requestedPath}` }
+    if (!existsSync(join(repoPath, '.git'))) return `Not a Git repository: ${requestedPath}`
     const graphPath = join(graphOutDirForRepo(repoPath), 'graph.json')
     let built = false
-    if (!existsSync(graphPath)) {
-        if (args.build === false) return `No graph yet for ${repoPath} (expected at ${graphPath}). Re-call without build:false to build one — large repos can take minutes.`
+    let upgrade = false
+    if (existsSync(graphPath)) {
+        try {
+            const saved = JSON.parse(readFileSync(graphPath, 'utf8'))
+            upgrade = !Number.isInteger(saved.edgeTypesV) || saved.edgeTypesV < 1
+        } catch {
+            upgrade = true
+        }
+    }
+    if (!existsSync(graphPath) || upgrade) {
+        if (args.build === false) {
+            return upgrade
+                ? `The existing graph for ${repoPath} predates typed import edges. Re-call without build:false to upgrade it before switching.`
+                : `No graph yet for ${repoPath} (expected at ${graphPath}). Re-call without build:false to build one — large repos can take minutes.`
+        }
         const mode = ['no-tests', 'tests-only', 'full'].includes(args.mode) ? args.mode : 'full'
         const res = await buildGraphForRepo(repoPath, {mode, scope: ''})
         if (!res || !res.ok) return `Graph build failed for ${repoPath}: ${(res && res.error) || 'unknown error'}`
@@ -53,7 +71,8 @@ export async function tOpenRepo(g, args, ctx) {
         ctx.reload()
         return `Failed to load ${graphPath} — still targeting the previous repo (${prev.repoRoot || 'none'}).`
     }
-    return `Opened ${repoPath}${built ? ' (graph built fresh)' : ''}: ${loaded.nodes.length} nodes / ${loaded.links.length} edges. All tools now target this repo.`
+    const buildNote = built ? (upgrade ? ' (graph upgraded to typed import edges)' : ' (graph built fresh)') : ''
+    return `Opened ${repoPath}${buildNote}: ${loaded.nodes.length} nodes / ${loaded.links.length} edges. All tools now target this repo.`
 }
 
 // Sibling repos that already have a built graph in the central weavatrix-graphs folder — open_repo candidates.
@@ -94,16 +113,15 @@ export async function tRefreshAdvisories(g, args, ctx) {
     if (res.ok === false) return `Advisory refresh failed: ${res.error}`
     const meta = storeMeta()
     return [
-        `Advisory store refreshed from OSV.dev: ${res.queried} package versions queried, ${res.vulnerable} with known advisories (${res.fetched} advisory records fetched).`,
+        `Advisory store ${res.status === 'PARTIAL' ? 'partially refreshed' : 'refreshed'} from OSV.dev: ${res.queriedOk ?? res.queried}/${res.queried} package versions queried successfully, ${res.vulnerable} with known advisories (${res.fetched} advisory records fetched).`,
         res.unsupported ? `${res.unsupported} packages skipped (ecosystem not OSV-queryable — npm/PyPI/Go only).` : null,
         res.errors?.length ? `Partial: ${res.errors.length} request error(s), first: ${res.errors[0]}` : null,
         `Store: ${DEFAULT_STORE} (${meta.advisoryCount} advisories, fetched ${meta.fetchedAt}). run_audit now reflects it — offline.`,
     ].filter(Boolean).join('\n')
 }
 
-// Push the current graph.json to a user-configured endpoint (the weavatrix site's hosted graph view,
-// or any self-hosted collector). Off until WEAVATRIX_SYNC_URL is set. The payload is the graph only —
-// file paths, symbol names, and edges — never file contents.
+// Push the current graph.json to a user-configured endpoint. Off until WEAVATRIX_SYNC_URL is set.
+// The payload is graph metadata (paths, symbols/ranges, imports, edges, metrics), never file contents.
 export async function tSyncGraph(g, args, ctx) {
     const url = process.env.WEAVATRIX_SYNC_URL
     if (!url) {
@@ -111,21 +129,27 @@ export async function tSyncGraph(g, args, ctx) {
             + ' (and WEAVATRIX_SYNC_TOKEN for bearer auth) in the MCP registration env, then call again.'
     }
     if (!g) return 'No graph loaded — build one first (open_repo / rebuild_graph).'
-    let body
-    try { body = readFileSync(ctx.graphPath, 'utf8') } catch (e) { return `Cannot read ${ctx.graphPath}: ${e.message}` }
+    let raw
+    try { raw = JSON.parse(readFileSync(ctx.graphPath, 'utf8')) } catch (e) { return `Cannot read ${ctx.graphPath}: ${e.message}` }
+    let payload
+    try { payload = createSyncPayload(raw) } catch (e) {
+        return `Cannot sync: ${e.message}. Run rebuild_graph once before sync_graph.`
+    }
+    const body = JSON.stringify(payload)
     const repoName = String(ctx.repoRoot || '').replace(/[\\/]+$/, '').split(/[\\/]/).pop() || 'repo'
     try {
         const res = await fetch(url, {
             method: 'POST',
             headers: {
                 'content-type': 'application/json',
+                'x-weavatrix-payload-version': String(payload.syncPayloadV),
                 'x-weavatrix-repo': repoName,
                 ...(process.env.WEAVATRIX_SYNC_TOKEN ? {authorization: `Bearer ${process.env.WEAVATRIX_SYNC_TOKEN}`} : {}),
             },
             body,
         })
         if (!res.ok) return `Sync endpoint answered HTTP ${res.status} — graph NOT accepted.`
-        return `Graph for ${repoName} (${g.nodes.length} nodes / ${g.links.length} edges, ${Math.round(body.length / 1024)} KB) pushed to ${url}.`
+        return `Graph for ${repoName} (${payload.nodes.length} nodes / ${payload.links.length} edges, ${Math.round(Buffer.byteLength(body) / 1024)} KB) pushed to ${url}.`
     } catch (e) {
         return `Sync failed: ${e.message} — the graph stays local.`
     }

package/src/mcp/tools-graph.mjs

@@ -12,9 +12,11 @@ export function tGraphStats(g, ctx) {
     const symbols = g.nodes.length - files
     const relCount = {}
     const confCount = {}
+    let typeOnlyEdges = 0
     for (const e of g.links) {
         relCount[e.relation ?? '?'] = (relCount[e.relation ?? '?'] || 0) + 1
         if (e.confidence != null) confCount[e.confidence] = (confCount[e.confidence] || 0) + 1
+        if (e.typeOnly === true) typeOnlyEdges++
     }
     const comm = new Map()
     for (const n of g.nodes) {
@@ -33,6 +35,7 @@ export function tGraphStats(g, ctx) {
         ctx?.repoRoot ? `- Repo: ${ctx.repoRoot}` : null,
         `- Nodes: ${g.nodes.length} (${files} files, ${symbols} symbols)`,
         `- Edges: ${g.links.length}`,
+        g.edgeTypesV ? `- Typed-edge metadata: v${g.edgeTypesV} (${typeOnlyEdges} type-only edges)` : `- Typed-edge metadata: unavailable (rebuild_graph with Weavatrix 0.1.3+)`,
         `- Relations: ${fmt(relCount)}`,
         Object.keys(confCount).length ? `- Confidence: ${fmt(confCount)}` : null,
         `- Communities: ${comm.size} (top by size: ${topComm.map(([c, n]) => `#${c}=${n}`).join(', ')})`,
@@ -77,10 +80,10 @@ export function tGetNode(g, {label} = {}, ctx) {
 function dedupeEdges(list) {
     const grouped = new Map()
     for (const e of list) {
-        const key = `${e.relation || 'rel'}|${e.id}`
+        const key = `${e.relation || 'rel'}|${e.typeOnly === true ? 'type' : 'runtime'}|${e.id}`
         const cur = grouped.get(key)
         if (cur) cur.count += 1
-        else grouped.set(key, {id: e.id, relation: e.relation, count: 1})
+        else grouped.set(key, {id: e.id, relation: e.relation, typeOnly: e.typeOnly === true, count: 1})
     }
     return [...grouped.values()]
 }
@@ -99,7 +102,7 @@ export function tGetNeighbors(g, {label, relation_filter} = {}, ctx) {
     const outs = dedupeEdges(outsRaw)
     const ins = dedupeEdges(insRaw)
     const line = (e, dir) =>
-        `  ${dir === 'out' ? '→' : '←'} ${e.relation || 'rel'}  ${labelOf(g, e.id)}  [${e.id}]${e.count > 1 ? `  (${e.count} sites)` : ''}`
+        `  ${dir === 'out' ? '→' : '←'} ${e.typeOnly ? 'type-only ' : ''}${e.relation || 'rel'}  ${labelOf(g, e.id)}  [${e.id}]${e.count > 1 ? `  (${e.count} sites)` : ''}`
     return [
         note,
         `Neighbors of ${n.label ?? id}${rf ? ` (relation=${rf})` : ''}: ${outs.length + ins.length} unique (${outsRaw.length + insRaw.length} edges)`,
@@ -113,21 +116,52 @@ export function tGetNeighbors(g, {label, relation_filter} = {}, ctx) {
 
 export function tGodNodes(g, {top_n = 10} = {}) {
     const n = Math.max(1, Math.min(100, Number(top_n) || 10))
-    const ranked = g.nodes
+    const scored = g.nodes
         .map((node) => {
-            const o = connList(g.out.get(String(node.id))).length
-            const i = connList(g.inn.get(String(node.id))).length
-            return {node, deg: o + i, out: o, in: i}
+            const outs = connList(g.out.get(String(node.id)))
+            const ins = connList(g.inn.get(String(node.id)))
+            const outIds = new Set(outs.map((e) => String(e.id)))
+            const inIds = new Set(ins.map((e) => String(e.id)))
+            const allIds = new Set([...outIds, ...inIds])
+            const runtimeIds = new Set([...outs, ...ins].filter((e) => e.typeOnly !== true).map((e) => String(e.id)))
+            const compileOnlyIds = new Set([...outs, ...ins].filter((e) => e.typeOnly === true).map((e) => String(e.id)))
+            for (const id of runtimeIds) compileOnlyIds.delete(id)
+            const occurrences = outs.length + ins.length
+            return {
+                node,
+                deg: allIds.size,
+                runtime: runtimeIds.size,
+                compileOnly: compileOnlyIds.size,
+                out: outIds.size,
+                in: inIds.size,
+                occurrences,
+            }
         })
-        .sort((a, b) => b.deg - a.deg)
-        .slice(0, n)
+        .filter((entry) => entry.deg > 0)
+        .sort((a, b) => b.runtime - a.runtime || b.deg - a.deg || b.occurrences - a.occurrences)
+    const ranked = scored.slice(0, n)
+    const rankedIds = new Set(ranked.map((entry) => String(entry.node.id)))
+    // Unique neighbors measure coupling, but a large component repeatedly calling the same helper (for
+    // example i18n) can still be a valuable complexity hotspot. Preserve that second lens explicitly
+    // instead of letting repeated sites inflate the coupling rank.
+    const occurrenceHotspots = scored
+        .filter((entry) => !rankedIds.has(String(entry.node.id)))
+        .filter((entry) => entry.occurrences >= 20 && entry.occurrences - entry.deg >= 10)
+        .sort((a, b) => (b.occurrences - b.deg) - (a.occurrences - a.deg) || b.occurrences - a.occurrences)
+        .slice(0, Math.min(5, n))
     return [
-        `Top ${n} most-connected nodes (call/import/reference edges, excluding structural containment):`,
+        `Top ${ranked.length} connectivity hubs (ranked by unique runtime call/import/reference neighbors; structural containment excluded):`,
         ...ranked.map(
             (r, i) =>
-                `${String(i + 1).padStart(2)}. ${r.node.label ?? r.node.id}  (${r.deg} edges: out ${r.out}, in ${r.in})  [${r.node.id}]`
+                `${String(i + 1).padStart(2)}. ${r.node.label ?? r.node.id}  (${r.deg} unique: ${r.runtime} runtime, ${r.compileOnly} compile-only; out ${r.out}, in ${r.in}; ${r.occurrences} edge occurrence${r.occurrences === 1 ? '' : 's'})  [${r.node.id}]`
+        ),
+        `Repeated call sites affect the occurrence count, not the connectivity rank; compile-only neighbors are secondary to runtime coupling.`,
+        occurrenceHotspots.length ? `` : null,
+        occurrenceHotspots.length ? `High occurrence hotspots outside the connectivity rank (repeated call/reference sites; complexity signal, not broader coupling):` : null,
+        ...occurrenceHotspots.map((r) =>
+            `  ${r.node.label ?? r.node.id}  (${r.occurrences} occurrences across ${r.deg} unique neighbors; ${r.occurrences - r.deg} repeats)  [${r.node.id}]`
         ),
-    ].join('\n')
+    ].filter((line) => line != null).join('\n')
 }
 
 export function tGetCommunity(g, {community_id} = {}) {