weavatrix 0.1.4 → 0.2.0

package/src/mcp/evidence-snapshot.package-graph.mjs

@@ -0,0 +1,249 @@
+import {createHash} from 'node:crypto'
+import {readFileSync, statSync} from 'node:fs'
+import {createRepoBoundary} from '../repo-path.js'
+import {CAPS, STATE, compareText, safeToken} from './evidence-snapshot.common.mjs'
+
+const LOCKFILES = ['npm-shrinkwrap.json', 'package-lock.json']
+const MAX_LOCKFILE_BYTES = 64 * 1024 * 1024
+const MAX_PACKAGE_RECORDS = 50_000
+const MAX_DEPENDENCY_DECLARATIONS = 200_000
+const PACKAGE_NAME = /^(?:@[a-z0-9._-]+\/)?[a-z0-9][a-z0-9._-]*$/i
+const PACKAGE_VERSION = /^[A-Za-z0-9][A-Za-z0-9._+~-]*$/
+
+const packageVersion = (value) => {
+    const version = safeToken(value, 128)
+    return version && PACKAGE_VERSION.test(version) ? version : null
+}
+
+const emptyCount = () => ({total: 0, returned: 0, truncated: false})
+const emptyDeclarations = () => ({total: 0, resolved: 0, unresolved: 0, local: 0, optionalMissing: 0})
+
+function emptyGraph(state, reason, extras = {}) {
+    return {
+        state,
+        ecosystem: 'npm',
+        root: '(root)',
+        ...extras,
+        completeness: {
+            nodes: emptyCount(),
+            edges: emptyCount(),
+            declarations: emptyDeclarations(),
+            reasons: reason ? [reason] : [],
+        },
+        nodes: [],
+        edges: [],
+    }
+}
+
+function normalizeLockPath(value) {
+    if (typeof value !== 'string' || value.length > 4096 || /[\u0000-\u001f\u007f]/.test(value)) return null
+    const raw = value.replace(/\\/g, '/')
+    if (/^(?:[a-z][a-z0-9+.-]*:|\/)/i.test(raw)) return null
+    const normalized = raw.replace(/\/$/, '')
+    if (normalized === '') return ''
+    const parts = normalized.split('/')
+    return parts.every((part) => part && part !== '.' && part !== '..') ? normalized : null
+}
+
+function packageNameFromPath(packagePath) {
+    const match = packagePath.match(/(?:^|\/)node_modules\/((?:@[^/]+\/)?[^/]+)$/)
+    const name = match?.[1]
+    return name && name.length <= 256 && PACKAGE_NAME.test(name) ? name : null
+}
+
+function packageId(name, version, packagePath) {
+    const location = createHash('sha256').update(packagePath).digest('hex').slice(0, 12)
+    return `npm:${name}@${version}:${location}`
+}
+
+function parentInstallPath(packagePath) {
+    const marker = packagePath.lastIndexOf('/node_modules/')
+    return marker >= 0 ? packagePath.slice(0, marker) : ''
+}
+
+function dependencyDeclarations(record) {
+    const declarations = new Map()
+    const add = (values, kind, replace = false) => {
+        if (!values || typeof values !== 'object' || Array.isArray(values)) return
+        for (const name of Object.keys(values)) {
+            if (name.length > 256 || !PACKAGE_NAME.test(name)) continue
+            if (replace || !declarations.has(name)) declarations.set(name, kind)
+        }
+    }
+    add(record?.dependencies, 'runtime')
+    add(record?.devDependencies, 'dev')
+    add(record?.optionalDependencies, 'optional', true)
+    if (record?.peerDependencies && typeof record.peerDependencies === 'object' && !Array.isArray(record.peerDependencies)) {
+        for (const name of Object.keys(record.peerDependencies)) {
+            if (name.length > 256 || !PACKAGE_NAME.test(name) || declarations.has(name)) continue
+            const optional = record?.peerDependenciesMeta?.[name]?.optional === true
+            declarations.set(name, optional ? 'optional-peer' : 'peer')
+        }
+    }
+    return [...declarations].map(([name, kind]) => ({name, kind}))
+        .sort((a, b) => compareText(a.name, b.name) || compareText(a.kind, b.kind))
+}
+
+function resolveDependency(sourcePath, name, records, externalNodes) {
+    let cursor = sourcePath
+    const seen = new Set()
+    while (!seen.has(cursor)) {
+        seen.add(cursor)
+        const candidate = cursor ? `${cursor}/node_modules/${name}` : `node_modules/${name}`
+        const record = records.get(candidate)
+        if (record) {
+            if (record.link === true) return {kind: 'local'}
+            const node = externalNodes.get(candidate)
+            return node ? {kind: 'external', node} : {kind: 'unresolved'}
+        }
+        if (!cursor) break
+        cursor = parentInstallPath(cursor)
+    }
+    return {kind: 'unresolved'}
+}
+
+function parseLock(lock, lockfile) {
+    const lockfileVersion = Number(lock?.lockfileVersion || 0)
+    const extras = {lockfile, lockfileVersion: Number.isFinite(lockfileVersion) ? Math.trunc(lockfileVersion) : 0}
+    if (![2, 3].includes(lockfileVersion) || !lock?.packages || typeof lock.packages !== 'object' || Array.isArray(lock.packages)) {
+        return emptyGraph(STATE.PARTIAL, 'PACKAGE_LOCK_V2_V3_REQUIRED', extras)
+    }
+
+    const allKeys = Object.keys(lock.packages).sort(compareText)
+    const selectedKeys = allKeys.slice(0, MAX_PACKAGE_RECORDS)
+    const reasons = []
+    if (selectedKeys.length < allKeys.length) reasons.push('LOCKFILE_PACKAGE_RECORD_LIMIT_REACHED')
+
+    const records = new Map()
+    let invalidRecords = 0
+    for (const rawPath of selectedKeys) {
+        const packagePath = normalizeLockPath(rawPath)
+        const record = lock.packages[rawPath]
+        if (packagePath == null || !record || typeof record !== 'object' || Array.isArray(record)) {
+            invalidRecords++
+            continue
+        }
+        const insideNodeModules = packagePath.startsWith('node_modules/') || packagePath.includes('/node_modules/')
+        if (insideNodeModules && !packageNameFromPath(packagePath)) {
+            invalidRecords++
+            continue
+        }
+        if (records.has(packagePath)) {
+            invalidRecords++
+            continue
+        }
+        records.set(packagePath, record)
+    }
+    if (invalidRecords > 0) reasons.push('INVALID_LOCKFILE_PACKAGE_RECORDS')
+
+    const externalNodes = new Map()
+    let invalidPackageVersions = 0
+    for (const [packagePath, record] of records) {
+        const name = packageNameFromPath(packagePath)
+        const version = packageVersion(record.version)
+        if (!name || record.link === true) continue
+        if (!version) { invalidPackageVersions++; continue }
+        externalNodes.set(packagePath, {
+            id: packageId(name, version, packagePath),
+            name,
+            version,
+            direct: false,
+            dev: record.dev === true || record.devOptional === true,
+            optional: record.optional === true || record.devOptional === true,
+            peer: record.peer === true,
+        })
+    }
+    if (invalidPackageVersions > 0) reasons.push('INVALID_LOCKFILE_PACKAGE_VERSIONS')
+
+    const edgeMap = new Map()
+    const declarations = emptyDeclarations()
+    let declarationLimitReached = false
+    const sources = [...records].filter(([packagePath]) =>
+        packageNameFromPath(packagePath) == null || externalNodes.has(packagePath))
+        .sort(([a], [b]) => compareText(a, b))
+
+    outer: for (const [sourcePath, record] of sources) {
+        const sourceNode = externalNodes.get(sourcePath)
+        const sourceId = sourceNode?.id || '(root)'
+        for (const declaration of dependencyDeclarations(record)) {
+            if (declarations.total >= MAX_DEPENDENCY_DECLARATIONS) {
+                declarationLimitReached = true
+                break outer
+            }
+            declarations.total++
+            const resolved = resolveDependency(sourcePath, declaration.name, records, externalNodes)
+            if (resolved.kind === 'local') {
+                declarations.local++
+                continue
+            }
+            if (resolved.kind !== 'external') {
+                if (declaration.kind === 'optional' || declaration.kind === 'optional-peer') declarations.optionalMissing++
+                else declarations.unresolved++
+                continue
+            }
+            declarations.resolved++
+            if (sourceId === '(root)') resolved.node.direct = true
+            if (sourceId === resolved.node.id) continue
+            const edge = {from: sourceId, to: resolved.node.id, kind: declaration.kind}
+            edgeMap.set(`${edge.from}\0${edge.to}\0${edge.kind}`, edge)
+        }
+    }
+    if (declarationLimitReached) reasons.push('LOCKFILE_DEPENDENCY_DECLARATION_LIMIT_REACHED')
+    if (declarations.unresolved > 0) reasons.push('UNRESOLVED_LOCKFILE_DEPENDENCIES')
+
+    const allNodes = [...externalNodes.values()].sort((a, b) =>
+        Number(b.direct) - Number(a.direct) || compareText(a.name, b.name) ||
+        compareText(a.version, b.version) || compareText(a.id, b.id))
+    const nodes = allNodes.slice(0, CAPS.packageGraphNodes)
+    const nodeIds = new Set(nodes.map((node) => node.id))
+    const allEdges = [...edgeMap.values()].sort((a, b) =>
+        compareText(a.from, b.from) || compareText(a.to, b.to) || compareText(a.kind, b.kind))
+    const eligibleEdges = allEdges.filter((edge) =>
+        (edge.from === '(root)' || nodeIds.has(edge.from)) && nodeIds.has(edge.to))
+    const edges = eligibleEdges.slice(0, CAPS.packageGraphEdges)
+    const nodesTruncated = nodes.length < allNodes.length
+    const edgesTruncated = edges.length < allEdges.length
+    if (nodesTruncated) reasons.push('PACKAGE_NODE_LIMIT_REACHED')
+    if (edgesTruncated) reasons.push('PACKAGE_EDGE_LIMIT_REACHED')
+
+    return {
+        state: reasons.length ? STATE.PARTIAL : STATE.COMPLETE,
+        ecosystem: 'npm',
+        lockfile,
+        lockfileVersion,
+        root: '(root)',
+        completeness: {
+            nodes: {total: allNodes.length, returned: nodes.length, truncated: nodesTruncated},
+            edges: {total: allEdges.length, returned: edges.length, truncated: edgesTruncated},
+            declarations,
+            reasons: [...new Set(reasons)].sort(compareText),
+        },
+        nodes,
+        edges,
+    }
+}
+
+export function buildPackageDependencyGraph(repoRoot) {
+    const boundary = createRepoBoundary(repoRoot)
+    if (!boundary.root) return emptyGraph(STATE.ERROR, 'INVALID_REPOSITORY_ROOT')
+
+    let selected = null
+    for (const lockfile of LOCKFILES) {
+        const resolved = boundary.resolve(lockfile)
+        if (resolved.ok) {
+            selected = {lockfile, path: resolved.path}
+            break
+        }
+    }
+    if (!selected) return emptyGraph(STATE.NOT_APPLICABLE, 'PACKAGE_LOCK_V2_V3_NOT_FOUND')
+
+    try {
+        if (statSync(selected.path).size > MAX_LOCKFILE_BYTES) {
+            return emptyGraph(STATE.ERROR, 'PACKAGE_LOCK_SIZE_LIMIT_REACHED', {lockfile: selected.lockfile})
+        }
+        const lock = JSON.parse(readFileSync(selected.path, 'utf8'))
+        return parseLock(lock, selected.lockfile)
+    } catch {
+        return emptyGraph(STATE.ERROR, 'PACKAGE_LOCK_READ_ERROR', {lockfile: selected.lockfile})
+    }
+}

package/src/mcp/evidence-snapshot.structure.mjs

@@ -0,0 +1,81 @@
+import {createHash} from 'node:crypto'
+import {readFileSync} from 'node:fs'
+import {buildFileImportGraph, checkBoundaries, findSccs, representativeCycle} from '../analysis/dep-rules.js'
+import {createRepoBoundary} from '../repo-path.js'
+import {CAPS, bounded, compareText, repoRelativePath, safeToken} from './evidence-snapshot.common.mjs'
+
+const MAX_CYCLE_MEMBERS = 200
+const SEVERITIES = new Set(['critical', 'high', 'medium', 'low', 'info'])
+const hash = (value) => createHash('sha256').update(value).digest('hex').slice(0, 24)
+
+function sortedSccs(adjacency) {
+    return findSccs(adjacency)
+        .map((members) => members.map((member) => repoRelativePath(member)).filter(Boolean).sort(compareText))
+        .filter((members) => members.length > 1)
+        .sort((a, b) => b.length - a.length || compareText(a.join('\0'), b.join('\0')))
+}
+
+function cycleFact(kind, adjacency, members) {
+    const representative = representativeCycle(adjacency, members).map((member) => repoRelativePath(member)).filter(Boolean)
+    return {
+        id: hash(`${kind}\0${members.join('\0')}`),
+        kind,
+        size: members.length,
+        members: members.slice(0, MAX_CYCLE_MEMBERS),
+        membersTruncated: members.length > MAX_CYCLE_MEMBERS,
+        representativePath: representative.slice(0, MAX_CYCLE_MEMBERS + 1),
+    }
+}
+
+function readRules(repoRoot) {
+    try {
+        const boundary = createRepoBoundary(repoRoot)
+        const resolved = boundary.resolve('.weavatrix-deps.json')
+        if (!resolved.ok) return {rules: {}, state: 'NOT_APPLICABLE'}
+        const parsed = JSON.parse(readFileSync(resolved.path, 'utf8'))
+        const hasRules = Array.isArray(parsed?.forbidden) && parsed.forbidden.length > 0 ||
+            Array.isArray(parsed?.allowedOnly) && parsed.allowedOnly.length > 0
+        return {rules: parsed && typeof parsed === 'object' ? parsed : {}, state: hasRules ? 'COMPLETE' : 'NOT_APPLICABLE'}
+    } catch {
+        return {rules: {}, state: 'ERROR'}
+    }
+}
+
+function boundaryFact(value) {
+    const from = repoRelativePath(value?.from), to = repoRelativePath(value?.to)
+    if (!from || !to || !['forbidden', 'allowedOnly'].includes(value?.kind)) return null
+    const name = safeToken(value?.name, 96)
+    return {
+        kind: value.kind,
+        ruleId: name || hash(String(value?.name || 'unnamed-rule')),
+        severity: SEVERITIES.has(value?.severity) ? value.severity : 'medium',
+        from,
+        to,
+    }
+}
+
+export function buildStructureEvidence(graph, repoRoot) {
+    try {
+        const imports = buildFileImportGraph(graph)
+        const runtimeSccs = sortedSccs(imports.runtimeAdj)
+        const runtimeKeys = new Set(runtimeSccs.map((members) => members.join('\0')))
+        const compileSccs = sortedSccs(imports.allAdj).filter((members) => !runtimeKeys.has(members.join('\0')))
+        const allCycles = [
+            ...runtimeSccs.map((members) => cycleFact('runtime', imports.runtimeAdj, members)),
+            ...compileSccs.map((members) => cycleFact('compile-time', imports.allAdj, members)),
+        ].sort((a, b) => a.kind === b.kind ? b.size - a.size || compareText(a.id, b.id) : a.kind === 'runtime' ? -1 : 1)
+        const cycles = bounded(allCycles, CAPS.architectureFindings)
+        const rules = readRules(repoRoot)
+        const allBoundaries = checkBoundaries(imports.runtimeEdges, rules.rules)
+            .map(boundaryFact).filter(Boolean)
+            .sort((a, b) => compareText(a.ruleId, b.ruleId) || compareText(a.from, b.from) || compareText(a.to, b.to))
+        const boundaries = bounded(allBoundaries, CAPS.architectureFindings)
+        return {state: 'COMPLETE', rulesState: rules.state, cycles, boundaries}
+    } catch {
+        return {
+            state: 'ERROR', rulesState: 'ERROR',
+            cycles: {items: [], completeness: {total: 0, returned: 0, truncated: false}},
+            boundaries: {items: [], completeness: {total: 0, returned: 0, truncated: false}},
+        }
+    }
+}

package/src/mcp/graph-context.mjs

@@ -40,6 +40,9 @@ export function loadGraph(path) {
             ...(e.compileOnly === true ? {compileOnly: true} : {}),
             ...(Number.isInteger(e.line) ? {line: e.line} : {}),
             ...(typeof e.specifier === 'string' ? {specifier: e.specifier} : {}),
+            ...(e.barrelProxy === true ? {barrelProxy: true} : {}),
+            ...(e.semanticOrigin === true ? {semanticOrigin: true} : {}),
+            ...(typeof e.viaBarrel === 'string' ? {viaBarrel: e.viaBarrel} : {}),
         }
         push(out, s, {id: t, ...metadata})
         push(inn, t, {id: s, ...metadata})
@@ -48,6 +51,18 @@ export function loadGraph(path) {
         nodes, links, byId, byLabel, out, inn,
         repoBoundaryV: Number(raw.repoBoundaryV) || 0,
         edgeTypesV: Number(raw.edgeTypesV) || 0,
+        barrelResolutionV: Number(raw.barrelResolutionV) || 0,
+        extractorSchemaV: Number(raw.extractorSchemaV) || 0,
+        extImportsV: Number(raw.extImportsV) || 0,
+        complexityV: Number(raw.complexityV) || 0,
+        graphBuildMode: ['full', 'no-tests', 'tests-only'].includes(raw.graphBuildMode) ? raw.graphBuildMode : 'full',
+        graphBuildScope: typeof raw.graphBuildScope === 'string' ? raw.graphBuildScope : null,
+        graphRevision: typeof raw.graphRevision === 'string' ? raw.graphRevision : null,
+        repositoryFreshnessProbeV: Number(raw.repositoryFreshnessProbeV) || 0,
+        repositoryFreshnessBuilderSchemaV: Number(raw.repositoryFreshnessBuilderSchemaV) || 0,
+        repositoryFreshnessBuilderVersion: typeof raw.repositoryFreshnessBuilderVersion === 'string' ? raw.repositoryFreshnessBuilderVersion : null,
+        repositoryFreshnessProbe: typeof raw.repositoryFreshnessProbe === 'string' ? raw.repositoryFreshnessProbe : null,
+        repositoryFreshnessMode: typeof raw.repositoryFreshnessMode === 'string' ? raw.repositoryFreshnessMode : null,
     }
 }
 
@@ -59,7 +74,7 @@ export const labelOf = (g, id) => {
 
 // Connectivity ignores structural file/symbol and class/method ownership, so runtime/compile-time
 // dependency ranks never treat nesting as a call or import.
-export const connList = (list) => (list || []).filter((e) => !isStructuralRelation(e.relation))
+export const connList = (list) => (list || []).filter((e) => !isStructuralRelation(e.relation) && e.barrelProxy !== true)
 export const degreeOf = (g, id) => connList(g.out.get(id)).length + connList(g.inn.get(id)).length
 export const uniqueConnCount = (list) => new Set(connList(list).map((e) => String(e.id))).size
 
@@ -101,28 +116,97 @@ export function ambiguityNote(query, info) {
 const bestByDegree = (g, list) =>
     list.reduce((best, n) => (degreeOf(g, n.id) > degreeOf(g, best.id) ? n : best), list[0])
 
-// seeds for traversal/search: rank substring/token matches by degree
+const QUERY_STOP = new Set('a an and are around architecture code do does explain find for from how in is me of or project repository show the through to trace what where which with'.split(' '))
+const QUERY_INTENTS = [
+    ['bootstrap', ['bootstrap', 'startup', 'entrypoint', 'entry', 'main', 'root', 'app', 'index']],
+    ['auth', ['auth', 'authentication', 'authorization', 'login', 'session', 'authgate']],
+    ['routing', ['routing', 'router', 'routes', 'route', 'navigation']],
+    ['layout', ['layout', 'layouts', 'shell']],
+    ['api', ['api', 'apis', 'endpoint', 'endpoints', 'client']],
+    ['state', ['state', 'store', 'stores', 'reducer', 'context']],
+]
+const INTENT_BY_TERM = new Map(QUERY_INTENTS.flatMap(([id, terms]) => terms.map((term) => [term, {id, terms}])))
+const wordsOf = (value) => String(value ?? '').replace(/([a-z0-9])([A-Z])/g, '$1 $2').toLowerCase().split(/[^a-z0-9_]+/).filter(Boolean)
+const normPath = (value) => String(value ?? '').replace(/\\/g, '/').replace(/^\.\//, '').toLowerCase()
+
+function queryConcepts(query) {
+    const seen = new Set()
+    const concepts = []
+    for (const raw of wordsOf(query)) {
+        if (raw.length < 2 || QUERY_STOP.has(raw)) continue
+        const intent = INTENT_BY_TERM.get(raw)
+        const id = intent?.id || raw
+        if (seen.has(id)) continue
+        seen.add(id)
+        concepts.push({id, raw, terms: intent ? [raw, ...intent.terms.filter((term) => term !== raw)] : [raw]})
+    }
+    return concepts
+}
+
+function conceptScore(g, node, concept) {
+    const id = normPath(node.id)
+    const label = String(node.label ?? '').toLowerCase()
+    const source = normPath(node.source_file)
+    const stem = (label.split('/').pop() || '').replace(/\.[^.]+$/, '')
+    const words = new Set(wordsOf(`${node.id} ${node.label ?? ''} ${node.source_file ?? ''}`))
+    const segments = new Set(source.split('/').flatMap((part) => wordsOf(part.replace(/\.[^.]+$/, ''))))
+    let match = 0
+    concept.terms.forEach((term, index) => {
+        const primary = index === 0
+        if (label === term || stem === term) match = Math.max(match, primary ? 60 : 42)
+        else if (segments.has(term)) match = Math.max(match, primary ? 48 : 36)
+        else if (words.has(term)) match = Math.max(match, primary ? 36 : 25)
+        else if (term.length >= 4 && (id.includes(term) || label.includes(term))) match = Math.max(match, primary ? 12 : 7)
+    })
+    if (!match) return 0
+    const fileNode = !isSymbol(node.id)
+    const depth = source ? source.split('/').length : 9
+    const entryBoost = concept.id === 'bootstrap' && /^(bootstrap|main|app|index|root)$/.test(stem) ? 10 : 0
+    return match + (fileNode ? 7 : 0) + Math.max(0, 4 - depth) + entryBoost + Math.min(2, degreeOf(g, node.id) / 40)
+}
+
+// Natural-language graph search keeps one strong candidate per concept before filling by aggregate
+// score. This prevents a broad architecture question from spending every seed on one dense API area.
 export function findSeeds(g, query, limit = 8) {
-    const q = String(query ?? '').trim().toLowerCase()
-    if (!q) return []
-    const tokens = q.split(/[^a-z0-9_]+/i).filter((t) => t.length > 1)
-    const scored = []
-    for (const n of g.nodes) {
-        const hay = `${String(n.id)} ${String(n.label ?? '')} ${String(n.source_file ?? '')}`.toLowerCase()
-        let score = 0
-        if (hay.includes(q)) score += 5
-        for (const t of tokens) if (hay.includes(t)) score += 1
-        if (score > 0) scored.push({n, score: score + Math.min(3, degreeOf(g, n.id) / 20)})
+    const concepts = queryConcepts(query)
+    if (!concepts.length || limit <= 0) return []
+    const rows = g.nodes.map((node) => {
+        const scores = concepts.map((concept) => conceptScore(g, node, concept))
+        return {node, scores, total: Math.max(...scores) + scores.reduce((sum, score) => sum + score, 0) / 10}
+    })
+    const chosen = []
+    const used = new Set()
+    for (let index = 0; index < concepts.length && chosen.length < limit; index++) {
+        const best = rows.filter((row) => !used.has(String(row.node.id)) && row.scores[index] > 0)
+            .sort((a, b) => b.scores[index] - a.scores[index] || String(a.node.id).localeCompare(String(b.node.id)))[0]
+        if (best) { chosen.push(best.node); used.add(String(best.node.id)) }
+    }
+    rows.filter((row) => row.total > 0 && !used.has(String(row.node.id)))
+        .sort((a, b) => b.total - a.total || String(a.node.id).localeCompare(String(b.node.id)))
+        .slice(0, Math.max(0, limit - chosen.length))
+        .forEach((row) => chosen.push(row.node))
+    return chosen
+}
+
+export function resolveSeedFiles(g, requested, limit = 12) {
+    const files = Array.isArray(requested) ? requested.slice(0, limit) : []
+    const seeds = []
+    const missing = []
+    for (const raw of files) {
+        const wanted = normPath(raw)
+        const node = g.nodes.find((candidate) => !isSymbol(candidate.id)
+            && (normPath(candidate.id) === wanted || normPath(candidate.source_file) === wanted))
+        if (!node) missing.push(String(raw))
+        else if (!seeds.some((seed) => String(seed.id) === String(node.id))) seeds.push(node)
     }
-    scored.sort((a, b) => b.score - a.score)
-    return scored.slice(0, limit).map((s) => s.n)
+    return {seeds, missing}
 }
 
 // undirected adjacency for reachability (query/shortest path)
 export function undirectedNeighbors(g, id) {
     const seen = new Map()
-    for (const e of g.out.get(id) || []) seen.set(e.id, e.relation)
-    for (const e of g.inn.get(id) || []) if (!seen.has(e.id)) seen.set(e.id, e.relation)
+    for (const e of g.out.get(id) || []) if (e.barrelProxy !== true) seen.set(e.id, e.relation)
+    for (const e of g.inn.get(id) || []) if (e.barrelProxy !== true && !seen.has(e.id)) seen.set(e.id, e.relation)
     return seen
 }
 

package/src/mcp/graph-diff.mjs

@@ -13,25 +13,77 @@ export const edgeEndpoint = (v) => String(v && typeof v === 'object' ? v.id : v)
 export const fileOfId = (id) => { const s = String(id); const h = s.indexOf('#'); return h < 0 ? s : s.slice(0, h) }
 const folderOfFile = folderModuleOf
 
+const terminalLineSuffix = (id) => {
+    const raw = String(id)
+    return raw.includes('#') ? raw.replace(/@\d+$/, '') : raw
+}
+
+const sourceLine = (node) => {
+    const explicit = String(node?.source_location || '').match(/^L(\d+)/i)
+    if (explicit) return Number(explicit[1])
+    const suffix = String(node?.id || '').match(/@(\d+)$/)
+    return suffix ? Number(suffix[1]) : Number.MAX_SAFE_INTEGER
+}
+
+// Node ids retain source lines for precise read_source jumps, but location is not identity. This
+// comparison-only index keeps file/name/kind/export/signature shape stable across line shifts and
+// uses an ordinal only for true same-name overloads. Raw ids remain the user-facing evidence.
+function stableNodeIndex(graph) {
+    const groups = new Map()
+    for (const node of graph.nodes || []) {
+        const raw = String(node?.id ?? '')
+        if (!raw) continue
+        const stem = terminalLineSuffix(raw)
+        const params = Number.isInteger(node?.complexity?.params) ? node.complexity.params : ''
+        const signature = [stem, node?.symbol_kind || '', node?.exported === true ? 'exported' : '', params].join('\u0000')
+        if (!groups.has(signature)) groups.set(signature, [])
+        groups.get(signature).push(node)
+    }
+    const byRaw = new Map()
+    const rawByStable = new Map()
+    for (const [signature, nodes] of groups) {
+        nodes.sort((a, b) => sourceLine(a) - sourceLine(b) || String(a.id).localeCompare(String(b.id)))
+        nodes.forEach((node, ordinal) => {
+            const stable = `${signature}\u0000${ordinal}`
+            const raw = String(node.id)
+            byRaw.set(raw, stable)
+            rawByStable.set(stable, raw)
+        })
+    }
+    return {byRaw, rawByStable, keys: new Set(rawByStable.keys())}
+}
+
 // 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 oldBarrelResolutionV = Number(oldG.barrelResolutionV) || 0
+    const newBarrelResolutionV = Number(newG.barrelResolutionV) || 0
+    const oldExtractorSchemaV = Number(oldG.extractorSchemaV) || 0
+    const newExtractorSchemaV = Number(newG.extractorSchemaV) || 0
+    const schemaChanges = [
+        oldEdgeTypesV !== newEdgeTypesV ? `edges v${oldEdgeTypesV}→v${newEdgeTypesV}` : null,
+        oldBarrelResolutionV !== newBarrelResolutionV ? `barrels v${oldBarrelResolutionV}→v${newBarrelResolutionV}` : null,
+        oldExtractorSchemaV !== newExtractorSchemaV ? `extractor v${oldExtractorSchemaV}→v${newExtractorSchemaV}` : null,
+    ].filter(Boolean)
+    const schemaMigration = schemaChanges.length > 0
+    const oldNodeIndex = stableNodeIndex(oldG)
+    const newNodeIndex = stableNodeIndex(newG)
 
     const edgeClass = (l) => l.typeOnly === true ? 'type' : l.compileOnly === true ? 'compile' : 'runtime'
-    const edgeKey = (l) => `${edgeEndpoint(l.source)}|${l.relation || ''}|${schemaMigration ? 'untyped' : edgeClass(l)}|${edgeEndpoint(l.target)}`
-    const edgeSet = (graph) => new Set((graph.links || []).map(edgeKey))
-    const oldEdges = edgeSet(oldG)
-    const newEdges = edgeSet(newG)
+    const stableEndpoint = (index, value) => {
+        const raw = edgeEndpoint(value)
+        return index.byRaw.get(raw) || raw
+    }
+    const edgeKey = (l, index) => `${stableEndpoint(index, l.source)}|${l.relation || ''}|${schemaMigration ? 'untyped' : edgeClass(l)}|${stableEndpoint(index, l.target)}`
+    const edgeSet = (graph, index) => new Set((graph.links || []).map((l) => edgeKey(l, index)))
+    const oldEdges = edgeSet(oldG, oldNodeIndex)
+    const newEdges = edgeSet(newG, newNodeIndex)
 
     const moduleEdges = (graph, classification) => {
         const set = new Set()
         for (const l of graph.links || []) {
-            if (isStructuralRelation(l.relation)) continue
+            if (isStructuralRelation(l.relation) || l.barrelProxy === true) continue
             if (edgeClass(l) !== classification) continue
             const a = folderOfFile(fileOfId(edgeEndpoint(l.source)))
             const b = folderOfFile(fileOfId(edgeEndpoint(l.target)))
@@ -48,17 +100,17 @@ export function diffGraphs(oldG, newG) {
     const oldCompileMods = schemaMigration ? new Set() : moduleEdges(oldG, 'compile')
     const newCompileMods = schemaMigration ? new Set() : moduleEdges(newG, 'compile')
 
-    const incoming = (graph) => {
+    const incoming = (graph, index) => {
         const m = new Map()
         for (const l of graph.links || []) {
-            if (isStructuralRelation(l.relation)) continue
-            const t = edgeEndpoint(l.target)
+            if (isStructuralRelation(l.relation) || l.barrelProxy === true) continue
+            const t = stableEndpoint(index, l.target)
             m.set(t, (m.get(t) || 0) + 1)
         }
         return m
     }
-    const oldIn = incoming(oldG)
-    const newIn = incoming(newG)
+    const oldIn = incoming(oldG, oldNodeIndex)
+    const newIn = incoming(newG, newNodeIndex)
 
     const cycles = (graph, includeTypeOnly) => {
         try {
@@ -100,10 +152,10 @@ export function diffGraphs(oldG, newG) {
     }
 
     return {
-        schemaMigration: schemaMigration ? {from: oldEdgeTypesV, to: newEdgeTypesV} : null,
+        schemaMigration: schemaMigration ? {from: oldEdgeTypesV, to: newEdgeTypesV, changes: schemaChanges} : null,
         nodes: {
-            added: [...newNodes].filter((id) => !oldNodes.has(id)),
-            removed: [...oldNodes].filter((id) => !newNodes.has(id))
+            added: [...newNodeIndex.keys].filter((key) => !oldNodeIndex.keys.has(key)).map((key) => newNodeIndex.rawByStable.get(key)),
+            removed: [...oldNodeIndex.keys].filter((key) => !newNodeIndex.keys.has(key)).map((key) => oldNodeIndex.rawByStable.get(key))
         },
         edges: {
             added: [...newEdges].filter((k) => !oldEdges.has(k)).length,
@@ -118,7 +170,9 @@ export function diffGraphs(oldG, newG) {
             compileRemoved: [...oldCompileMods].filter((k) => !newCompileMods.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)),
+        orphaned: [...oldIn.keys()]
+            .filter((key) => newNodeIndex.keys.has(key) && !newIn.has(key))
+            .map((key) => newNodeIndex.rawByStable.get(key) || oldNodeIndex.rawByStable.get(key)),
         cycles: {
             runtime: schemaMigration ? null : cycleDelta(cycles(oldG, false), cycles(newG, false)),
             // Backward-compatible field name: since edgeTypesV 2 this includes typeOnly and compileOnly.
@@ -130,12 +184,12 @@ export function diffGraphs(oldG, newG) {
 export function formatGraphDiff(d) {
     if (!d.nodes.added.length && !d.nodes.removed.length && !d.edges.added && !d.edges.removed) {
         return d.schemaMigration
-            ? `Graph edge schema upgraded v${d.schemaMigration.from} → v${d.schemaMigration.to}; compile-time baseline established. Runtime/compile-time cycle and module classifications are intentionally not compared on this rebuild.`
+            ? `Graph extractor/schema upgraded (${d.schemaMigration.changes.join(', ')}); compile-time baseline established. Runtime/compile-time 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.schemaMigration) lines.push(`Graph edge schema upgraded v${d.schemaMigration.from} → v${d.schemaMigration.to}; runtime/compile-time cycle and module classifications are intentionally not compared until the next rebuild.`)
+    if (d.schemaMigration) lines.push(`Graph extractor/schema upgraded (${d.schemaMigration.changes.join(', ')}); runtime/compile-time 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 = []

package/src/mcp/staleness-notice.mjs

@@ -0,0 +1,20 @@
+// Staleness is important, but repeating an identical paragraph after every graph call drowns the
+// actual answer. Surface a changed condition immediately, then remind periodically. graph_stats can
+// force the notice because freshness is the purpose of that tool.
+export function createStalenessNoticeGate(cooldownMs = 5 * 60_000) {
+    let lastKey = ''
+    let lastShownAt = 0
+    return {
+        shouldShow({line, graphPath = '', force = false, now = Date.now()} = {}) {
+            if (!line) return false
+            const key = `${graphPath}\u0000${line}`
+            if (force || key !== lastKey || now - lastShownAt >= cooldownMs) {
+                lastKey = key
+                lastShownAt = now
+                return true
+            }
+            return false
+        },
+        reset() { lastKey = ''; lastShownAt = 0 },
+    }
+}