weavatrix 0.2.12 → 0.2.14

package/src/mcp/health/structure.mjs

@@ -0,0 +1,219 @@
+import {degreeOf, rawGraph} from '../graph-context.mjs'
+import {summarizeCommunities, aggregateGraph} from '../../analysis/graph-analysis.js'
+import {computeStaticTestReachability} from '../../analysis/static-test-reachability.js'
+import {computeHotPathReview} from '../../analysis/hot-path-review.js'
+import {createPathClassifier, hasPathClass} from '../../path-classification.js'
+import {toolResult} from '../tool-result.mjs'
+
+export function tListCommunities(g, args, ctx) {
+    const max = Math.max(1, Math.min(100, Number(args.top_n) || 20))
+    const list = summarizeCommunities(ctx.graphPath, max)
+    if (!list.length) return 'No communities found in the graph.'
+    return [
+        `Communities, largest first (list position = community_id for get_community):`,
+        ...list.map((c, i) => `${String(i).padStart(3)}. ${c.name} — ${c.size} nodes (raw id ${c.id}; e.g. ${[...new Set(c.files)].join(', ')})`),
+    ].join('\n')
+}
+
+// Folder-level architecture map: modules (top-two path segments) with file/symbol counts and the
+// strongest module→module dependencies. Pure graph aggregation — no filesystem reads.
+export function tModuleMap(g, args, ctx) {
+    const graph = rawGraph(ctx)
+    const testsOnly = graph.graphBuildMode === 'tests-only'
+    const includeNonProduct = args.include_non_product === true || testsOnly
+    const classifier = createPathClassifier(ctx?.repoRoot || null)
+    const nonProductFiles = new Set()
+    const classifiedFiles = new Set()
+    if (!includeNonProduct) {
+        for (const node of graph.nodes || []) {
+            if (!node?.source_file) continue
+            const sourceFile = String(node.source_file)
+            if (classifiedFiles.has(sourceFile)) continue
+            classifiedFiles.add(sourceFile)
+            const explanation = classifier.explain(sourceFile)
+            if (explanation.excluded || hasPathClass(explanation, 'test', 'e2e', 'generated', 'mock', 'story', 'docs', 'benchmark', 'temp')) {
+                nonProductFiles.add(sourceFile)
+            }
+        }
+    }
+    const visibleGraph = includeNonProduct || nonProductFiles.size === 0 ? graph : (() => {
+        const keep = new Set((graph.nodes || [])
+            .filter((node) => !node?.source_file || !nonProductFiles.has(String(node.source_file)))
+            .map((node) => String(node.id)))
+        const endpoint = (value) => String(value && typeof value === 'object' ? value.id : value)
+        return {
+            ...graph,
+            nodes: (graph.nodes || []).filter((node) => keep.has(String(node.id))),
+            links: (graph.links || []).filter((link) => keep.has(endpoint(link.source)) && keep.has(endpoint(link.target))),
+        }
+    })()
+    const agg = aggregateGraph(visibleGraph, null)
+    const topN = Math.max(1, Math.min(60, Number(args.top_n) || 25))
+    const mods = agg.modules.slice(0, topN)
+    const edges = agg.moduleEdges.slice(0, Math.min(50, topN * 2))
+    const compileEdges = new Map()
+    const collectCompileEdges = (list, kind) => {
+        for (const edge of list || []) {
+            const key = `${edge.from}\0${edge.to}`
+            const current = compileEdges.get(key) || {from: edge.from, to: edge.to, count: 0, typeOnly: 0, compileOnly: 0}
+            current.count += edge.count
+            current[kind] += edge.count
+            compileEdges.set(key, current)
+        }
+    }
+    collectCompileEdges(agg.typeOnlyModuleEdges, 'typeOnly')
+    collectCompileEdges(agg.compileOnlyModuleEdges, 'compileOnly')
+    const compiled = [...compileEdges.values()].sort((a, b) => b.count - a.count).slice(0, Math.min(50, topN * 2))
+    return [
+        testsOnly
+            ? 'Scope: tests-only graph; classified test/e2e/fixture surfaces are retained automatically.'
+            : includeNonProduct
+            ? 'Scope: all indexed files, including classified non-product surfaces.'
+            : `Scope: production-only (default); excluded ${nonProductFiles.size} classified test/fixture/benchmark/generated/docs file(s). Pass include_non_product:true for the complete graph.`,
+        `Module map: ${agg.totals.files} files in ${agg.modules.length} folder-modules, ${agg.totals.moduleEdges} runtime module dependencies and ${agg.totals.compileTimeModuleEdges || 0} compile-time dependencies (${agg.totals.typeOnlyModuleEdges || 0} type-only, ${agg.totals.compileOnlyModuleEdges || 0} compile-only). Top ${mods.length}:`,
+        ...mods.map((m) => `  ${m.name} — ${m.fileCount} files, ${m.symbolCount} symbols`),
+        ``,
+        `Strongest runtime module dependencies:`,
+        ...edges.map((e) => `  ${e.from} → ${e.to}  (${e.count})`),
+        compiled.length ? `` : null,
+        compiled.length ? `Compile-time module dependencies (not runtime coupling):` : null,
+        ...compiled.map((e) => `  ${e.from} → ${e.to}  (${e.count}; ${e.typeOnly} type-only, ${e.compileOnly} compile-only)`),
+    ].filter((line) => line != null).join('\n')
+}
+
+// Parser-backed local cost review. This keeps syntax, graph coupling and measured/static test
+// evidence as separate fields so callers cannot mistake a ranking heuristic for profiler output.
+export function tHotPathReview(g, args, ctx) {
+    const review = computeHotPathReview(rawGraph(ctx), {
+        repoRoot: ctx?.repoRoot || null,
+        path: args.path,
+        includeTests: args.include_tests === true,
+        includeClassified: args.include_classified === true,
+        topN: args.top_n,
+        cyclomaticThreshold: args.cyclomatic_threshold,
+        callThreshold: args.call_threshold,
+        loopDepthThreshold: args.loop_depth_threshold,
+        timeRankThreshold: args.time_rank_threshold,
+        minScore: args.min_score,
+    })
+    if (!review.ok) return toolResult(`Hot-path review refused: ${review.error}.`, review)
+    const pct = (value) => typeof value === 'number' ? `${Math.round(value * 100)}%` : String(value || 'NOT_AVAILABLE')
+    const coverageLine = review.coverage.actualCoverage === 'AVAILABLE'
+        ? `Measured coverage: ${review.coverage.measuredFiles} file(s) from ${review.coverage.sources.join(', ') || 'coverage report'}.`
+        : review.coverage.staticReachability
+            ? `actualCoverage: NOT_AVAILABLE; static test reachability ${review.coverage.staticReachability.reachableFiles}/${review.coverage.staticReachability.productFiles} product file(s).`
+            : 'actualCoverage: NOT_AVAILABLE; no measured or static test evidence was available.'
+    const text = [
+        `Local hot-path review: ${review.candidateSymbols} candidate(s) from ${review.analyzedSymbols} analyzed symbol(s); showing ${review.hotspots.length}.`,
+        `Thresholds: time rank >=${review.thresholds.timeRank}, cyclomatic >=${review.thresholds.cyclomatic}, calls >=${review.thresholds.calls}, loop depth >=${review.thresholds.loopDepth}, score >=${review.thresholds.minScore}.`,
+        `Selection: ${review.selectionPolicy.mode}${review.selectionPolicy.strongLocalFallback ? '; strong local sort/recursion/deep-loop evidence can pass below the blended score gate' : '; strict explicit score gate'}.`,
+        coverageLine,
+        'Local syntax cost and graph coupling are separate. Scores are review priority, not measured runtime.',
+        '',
+        ...(review.hotspots.length ? review.hotspots.flatMap((item, index) => {
+            const tests = item.testEvidence.actualCoverage === 'NOT_AVAILABLE'
+                ? item.testEvidence.staticReachable ? `static-test d${item.testEvidence.distance}` : 'no-static-test-path'
+                : `coverage ${pct(item.testEvidence.actualCoverage)}`
+            const pointer = `${item.file}${item.startLine ? `:${item.startLine}${item.endLine > item.startLine ? `-${item.endLine}` : ''}` : ''}`
+            const evidence = item.sourceEvidence.length
+                ? `\n       evidence: ${item.sourceEvidence.map((entry) => `${entry.kind}@L${entry.line || '?'}${entry.detail ? ` (${entry.detail})` : ''}`).join('; ')}`
+                : ''
+            return [
+                `  ${String(index + 1).padStart(2)}. score ${String(item.score).padStart(5)}  syntax ${String(item.localSyntax.score).padStart(5)}  graph ${String(item.graphRisk.score).padStart(5)}  ${item.confidence}`,
+                `      ${item.label}  (${pointer}; fan-in ${item.graphRisk.fanIn}, fan-out ${item.graphRisk.fanOut}; ${tests})`,
+                `       ${item.reasons.slice(0, 5).join('; ')}${evidence}`,
+            ]
+        }) : ['  (none at the selected thresholds)']),
+        review.bounds.truncated ? `... +${review.bounds.totalCandidates - review.bounds.returned} more (raise top_n to display more, raise min_score or narrow path to tighten; lower min_score to broaden).` : null,
+        '',
+        'Caveat: no interprocedural Big-O, recursion-bound, CFG, dead-store or taint-flow claim is made.',
+    ].filter((line) => line != null).join('\n')
+    return toolResult(text, review, {
+        completeness: {
+            symbols: 'COMPLETE_FOR_INDEXED_GRAPH',
+            output: review.bounds.truncated ? 'BOUNDED' : 'COMPLETE',
+            coverage: review.coverage.actualCoverage,
+        },
+    })
+}
+
+// Coverage × graph: map an EXISTING coverage report (istanbul/lcov/coverage.py/Go — read offline,
+// tests are never executed here) onto files and symbols, then rank refactor risk as
+// connectivity × uncovered share. Pairs with get_dependents: many dependents + low coverage ⇒ write
+// tests before changing. Coverage pcts in this layer are fractions (0..1).
+export function tCoverageMap(g, args, ctx) {
+    if (!ctx.repoRoot) return 'Coverage mapping needs the repo root (not provided to this server).'
+    const agg = aggregateGraph(rawGraph(ctx), ctx.repoRoot)
+    const pathFilter = args.path ? String(args.path).replace(/\\/g, '/').replace(/\/+$/, '') : null
+    const inScope = (p) => !pathFilter || p === pathFilter || String(p).startsWith(`${pathFilter}/`)
+    const allFiles = agg.modules.flatMap((m) => m.files.filter((f) => inScope(f.path)))
+    const measured = allFiles.filter((f) => f.coverage != null)
+    if (!measured.length) {
+        const fallback = computeStaticTestReachability(rawGraph(ctx), {repoRoot: ctx.repoRoot, path: pathFilter || ''})
+        const topN = Math.max(1, Math.min(50, Number(args.top_n) || 15))
+        const reachable = fallback.reachable.slice(0, topN)
+        const unreachable = fallback.unreachable.slice(0, topN)
+        return [
+            `Static test reachability${pathFilter ? ` for ${pathFilter}` : ''}: ${fallback.reachableFiles}/${fallback.productFiles} product file(s) have a runtime graph path from ${fallback.testFiles} indexed test file(s).`,
+            `actualCoverage: ${fallback.actualCoverage}. This is NOT coverage: imports/calls only show that a test can statically reach a file, never that a line, branch or symbol executed.`,
+            fallback.bounds.truncated ? `Traversal was bounded/truncated (${fallback.bounds.traversedStates}/${fallback.bounds.maxStates} states, depth ≤${fallback.bounds.maxDepth}, ${fallback.testFiles}/${fallback.totalTestFiles} test files).` : `Traversal: ${fallback.bounds.traversedStates} bounded state(s), depth ≤${fallback.bounds.maxDepth}.`,
+            '',
+            'Nearest runtime paths from tests:',
+            ...(reachable.length ? reachable.map((entry) => {
+                const nearest = entry.nearestTests[0]
+                return `  ${nearest.confidence.padStart(6)}  d${nearest.distance}  ${entry.file}  ← ${nearest.test}\n          path: ${nearest.path.join(' → ')}`
+            }) : ['  (none)']),
+            '',
+            `No runtime path from an indexed test (${fallback.unreachableFiles}; not proof of no tests):`,
+            ...(unreachable.length ? unreachable.map((file) => `  ${file}`) : ['  (none)']),
+            fallback.unreachableFiles > unreachable.length ? `  … +${fallback.unreachableFiles - unreachable.length} more (raise top_n or narrow path)` : null,
+            '',
+            'No coverage report found — generate one for measured coverage:',
+            'Generate one with the repo\'s own test runner, then call coverage_map again:',
+            '  JS/TS:  npx vitest run --coverage   (or jest --coverage)',
+            '  Python: pytest --cov --cov-report=json',
+            '  Go:     go test ./... -coverprofile=coverage.out',
+            'Read locations: coverage/coverage-summary.json, coverage/coverage-final.json, (coverage/)lcov.info, coverage.json, coverage.out.',
+        ].filter((line) => line != null).join('\n')
+    }
+    const pctStr = (v) => (v == null ? 'n/a' : `${Math.round(v * 100)}%`)
+    const sources = [...new Set(measured.map((f) => f.coverageSource).filter(Boolean))]
+    const avg = measured.reduce((s, f) => s + f.coverage, 0) / measured.length
+    const rollup = agg.modules
+        .map((m) => {
+            const withCov = m.files.filter((f) => f.coverage != null && inScope(f.path))
+            if (!withCov.length) return null
+            return {
+                name: m.name,
+                measured: withCov.length,
+                total: m.files.filter((f) => inScope(f.path)).length,
+                avg: withCov.reduce((s, f) => s + f.coverage, 0) / withCov.length,
+            }
+        })
+        .filter(Boolean)
+        .sort((a, b) => a.avg - b.avg)
+    const topN = Math.max(1, Math.min(50, Number(args.top_n) || 15))
+    // risk = graph degree × uncovered share; only symbols below 80% matter
+    const risky = agg.symbols
+        .filter((s) => s.coverage != null && s.coverage < 0.8 && inScope(s.file))
+        .map((s) => ({...s, degree: degreeOf(g, s.id)}))
+        .filter((s) => s.degree > 0)
+        .sort((a, b) => b.degree * (1 - b.coverage) - a.degree * (1 - a.coverage))
+        .slice(0, topN)
+    return [
+        `Coverage map (${measured.length}/${allFiles.length} files measured, avg ${pctStr(avg)}; report: ${sources.join(', ') || 'unknown'}${pathFilter ? `; filter ${pathFilter}` : ''}).`,
+        ``,
+        `Modules by average coverage (worst first):`,
+        ...rollup.slice(0, 20).map((m) => `  ${pctStr(m.avg).padStart(5)}  ${m.name}  (${m.measured}/${m.total} files measured)`),
+        ``,
+        `Refactor-risk hotspots — connected symbols with low coverage (ranked by degree × uncovered):`,
+        ...(risky.length
+            ? risky.map((s) => `  ${pctStr(s.coverage).padStart(5)}  deg ${String(s.degree).padStart(3)}  ${s.label}  (${s.file}${s.line ? `:${s.line}` : ''})`)
+            : ['  (none — every connected symbol is ≥80% covered or unmeasured)']),
+        ``,
+        `Tip: before refactoring a hotspot, run get_dependents on it — low coverage × many dependents means write tests first.`,
+    ].join('\n')
+}
+
+// HTTP endpoint inventory: Express/Fastify/Nest/Flask/FastAPI/Go/Rust/Spring route definitions.
+

package/src/mcp/runtime-version.mjs

@@ -0,0 +1,32 @@
+import {readFileSync} from 'node:fs'
+import process from 'node:process'
+
+export const STALE_RUNTIME_OVERRIDE_ENV = 'WEAVATRIX_ALLOW_STALE_RUNTIME'
+
+export function runtimeVersionStatus({runningVersion, packageJsonPath, allowStale} = {}) {
+    let diskVersion = null, packageVersionError = null
+    try {
+        const parsed = JSON.parse(readFileSync(packageJsonPath, 'utf8'))
+        diskVersion = typeof parsed?.version === 'string' && parsed.version.trim() ? parsed.version.trim() : null
+        if (!diskVersion) packageVersionError = 'package.json has no valid version'
+    } catch (error) {
+        packageVersionError = `package.json is unreadable: ${error.message}`
+    }
+    const staleRuntime = diskVersion !== String(runningVersion || '')
+    const staleRuntimeAllowed = allowStale == null
+        ? process.env[STALE_RUNTIME_OVERRIDE_ENV] === '1'
+        : allowStale === true
+    return {
+        version: String(runningVersion || ''),
+        diskVersion,
+        staleRuntime,
+        staleRuntimeAllowed,
+        ...(packageVersionError ? {packageVersionError} : {}),
+    }
+}
+
+export function staleRuntimeMessage(status) {
+    const disk = status.diskVersion || 'unavailable'
+    return `STALE_RUNTIME: running Weavatrix ${status.version || 'unknown'} but package.json on disk is ${disk}. Restart/reconnect the MCP server before using tools. For deliberate source-development only, set ${STALE_RUNTIME_OVERRIDE_ENV}=1.`
+}
+

package/src/mcp/server/auto-refresh.mjs

@@ -0,0 +1,66 @@
+import {dirname} from 'node:path'
+import {buildGraphForRepo, defaultPrecisionMode} from '../../build-graph.js'
+import {persistedFreshnessMatches, repositoryFreshnessProbe} from '../../graph/freshness-probe.js'
+import {PRECISION_OVERLAY_V, precisionSemanticInputsMatch, readPrecisionOverlay} from '../../precision/lsp-overlay.js'
+import {loadGraph} from '../graph-context.mjs'
+
+export function createAutoRefresh(getApi) {
+    const probeCache = new Map()
+    const configured = process.env.WEAVATRIX_AUTO_REFRESH_DEBOUNCE_MS == null
+        ? 2_000 : Number(process.env.WEAVATRIX_AUTO_REFRESH_DEBOUNCE_MS)
+    const debounceMs = Math.max(0, Math.min(5_000, Number.isFinite(configured) ? configured : 2_000))
+    return async function autoRefresh(callCtx, currentGraph) {
+        if (!callCtx?.repoRoot || !callCtx?.graphPath) return {graph: null, refresh: null}
+        const activePrecision = currentGraph?.graphPrecisionMode || defaultPrecisionMode()
+        const probeKey = `${callCtx.graphPath}\0${currentGraph?.graphBuildMode || 'full'}\0${activePrecision}`
+        let semanticInputsChanged = false
+        if (activePrecision === 'lsp' && currentGraph) {
+            try {
+                const overlay = readPrecisionOverlay(callCtx.graphPath, currentGraph)
+                semanticInputsChanged = typeof overlay?.semanticInputFingerprint === 'string'
+                    && !precisionSemanticInputsMatch(overlay, callCtx.repoRoot, currentGraph)
+            } catch {
+                semanticInputsChanged = true
+            }
+        }
+        const cached = probeCache.get(probeKey)
+        if (!semanticInputsChanged && currentGraph && cached && Date.now() - cached.checkedAt < debounceMs) {
+            return {graph: currentGraph, refresh: {kind: 'none', revision: currentGraph.graphRevision || null, changedFiles: 0}}
+        }
+        const beforeProbe = repositoryFreshnessProbe(callCtx.repoRoot)
+        const precisionMissing = activePrecision === 'lsp' && (
+            Number(currentGraph?.precisionOverlayV) !== PRECISION_OVERLAY_V || semanticInputsChanged
+        )
+        if (!precisionMissing && beforeProbe && currentGraph && (
+            cached?.probe === beforeProbe
+            || persistedFreshnessMatches(currentGraph, beforeProbe, currentGraph.graphBuildMode || 'full')
+        )) {
+            probeCache.set(probeKey, {probe: beforeProbe, checkedAt: Date.now()})
+            return {graph: currentGraph, refresh: {kind: 'none', revision: currentGraph.graphRevision || null, changedFiles: 0}}
+        }
+        const result = await buildGraphForRepo(callCtx.repoRoot, {
+            mode: currentGraph?.graphBuildMode || 'full',
+            precision: activePrecision,
+            scope: '',
+            outDir: dirname(callCtx.graphPath),
+        })
+        if (!result.ok) throw new Error(result.error || 'automatic graph refresh failed')
+        getApi().resetStalenessCache()
+        const fresh = loadGraph(callCtx.graphPath, {repoRoot: callCtx.repoRoot})
+        const afterProbe = repositoryFreshnessProbe(callCtx.repoRoot)
+        if (afterProbe && afterProbe === beforeProbe) probeCache.set(probeKey, {probe: afterProbe, checkedAt: Date.now()})
+        else probeCache.delete(probeKey)
+        const update = result.refresh || {kind: 'full', changedFiles: [], reason: 'automatic-refresh'}
+        return {
+            graph: fresh,
+            refresh: {
+                kind: update.kind,
+                revision: update.revision || fresh.graphRevision || null,
+                changedFiles: Array.isArray(update.changedFiles) ? update.changedFiles.length : 0,
+                notice: update.kind === 'none'
+                    ? undefined
+                    : `Graph ${update.kind === 'incremental' ? 'incrementally refreshed' : 'rebuilt'} before this answer (${update.reason || 'repository changed'}).`,
+            },
+        }
+    }
+}

package/src/mcp/server/runtime-config.mjs

@@ -0,0 +1,43 @@
+import {createRequire} from 'node:module'
+import {existsSync, realpathSync, statSync} from 'node:fs'
+import {dirname, join} from 'node:path'
+import {fileURLToPath} from 'node:url'
+import {graphOutDirForRepo} from '../../graph/layout.js'
+
+const SOURCE_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', '..')
+const MCP_DIR = join(SOURCE_DIR, 'mcp')
+const CATALOG_URL = new URL('../catalog.mjs', import.meta.url)
+
+export const PACKAGE_JSON_PATH = join(SOURCE_DIR, '..', 'package.json')
+export const PACKAGE_VERSION = (() => {
+    try { return createRequire(import.meta.url)('../../../package.json').version } catch { return '0.0.0' }
+})()
+export const SERVER_INFO = {name: 'weavatrix', version: PACKAGE_VERSION}
+
+export const loadServerCatalog = (version = 0) => import(version ? `${CATALOG_URL.href}?v=${version}` : CATALOG_URL.href)
+
+export function hotCatalogVersion(hotFiles) {
+    let version = 0
+    for (const file of hotFiles) {
+        try {
+            const modified = statSync(join(MCP_DIR, file)).mtimeMs
+            if (modified > version) version = modified
+        } catch { /* a missing file does not bump the version */ }
+    }
+    return version
+}
+
+export function resolveServerTarget(argv, log = () => {}) {
+    let graphPath = argv[2], repoArg = argv[3], capabilities = argv[4]
+    try {
+        if (graphPath && statSync(graphPath).isDirectory()) {
+            repoArg = realpathSync.native(graphPath)
+            capabilities = argv[3]
+            graphPath = join(graphOutDirForRepo(repoArg), 'graph.json')
+            if (!existsSync(graphPath)) log(`no graph built yet for ${repoArg} — ask the agent to call rebuild_graph; it builds into the standard weavatrix-graphs layout`)
+        }
+    } catch { /* argv[2] is a graph path or unavailable */ }
+    let repoRoot = null
+    try { if (repoArg && statSync(repoArg).isDirectory()) repoRoot = realpathSync.native(repoArg) } catch { /* invalid repo root */ }
+    return {graphPath, repoRoot, capabilities}
+}

package/src/mcp/server/shutdown.mjs

@@ -0,0 +1,40 @@
+import process from 'node:process'
+import {
+    activeLspClientCount,
+    beginLspClientShutdown,
+    shutdownActiveLspClients,
+} from '../../precision/lsp-client.js'
+
+async function settleWithin(promise, timeoutMs) {
+    let timer
+    const settled = await Promise.race([
+        Promise.resolve(promise).then(() => true, () => true),
+        new Promise((resolve) => { timer = setTimeout(() => resolve(false), timeoutMs) }),
+    ])
+    if (timer) clearTimeout(timer)
+    return settled
+}
+
+export function createShutdownController({log, targetMutation}) {
+    let shuttingDown = false, shutdownPromise = null
+    const request = (reason, exitCode = 0) => {
+        if (shutdownPromise) return shutdownPromise
+        shuttingDown = true
+        beginLspClientShutdown()
+        process.stdin.pause()
+        const activeAtStart = activeLspClientCount()
+        log(`shutdown requested (${reason}); draining graph work and ${activeAtStart} semantic provider(s)`)
+        shutdownPromise = (async () => {
+            const initiallyDrained = await settleWithin(targetMutation(), 2_500)
+            const semantic = await shutdownActiveLspClients({timeoutMs: 3_000})
+            const fullyDrained = initiallyDrained || await settleWithin(targetMutation(), 1_500)
+            log(`shutdown cleanup: graph=${fullyDrained ? 'drained' : 'bounded-timeout'}, semantic=${semantic.requested} requested/${semantic.remaining} remaining${semantic.timedOut ? ' (forced)' : ''}`)
+        })().catch((error) => {
+            log(`shutdown cleanup failed: ${error.stack || error.message}`)
+        }).finally(() => {
+            process.exit(exitCode)
+        })
+        return shutdownPromise
+    }
+    return {isShuttingDown: () => shuttingDown, request}
+}

package/src/mcp/sync/evidence-architecture.mjs

@@ -0,0 +1,54 @@
+import {
+    CAPS, SEVERITIES, bool, compare, count, int, list, moduleId, path,
+    reasons, state, text, token, verdict,
+} from './evidence-common.mjs'
+
+function moduleFact(value) {
+    const id = moduleId(value?.id || value?.name)
+    return id ? {id, fileCount: int(value.fileCount), nodeCount: int(value.nodeCount), symbolCount: int(value.symbolCount)} : null
+}
+
+function dependency(value) {
+    const from = moduleId(value?.from), to = moduleId(value?.to)
+    return from && to && from !== to ? {from, to, count: int(value.count)} : null
+}
+
+function cycleFact(value) {
+    const id = text(value?.id, 64), kind = value?.kind
+    if (!id || !/^[a-f0-9]{16,64}$/i.test(id) || !['runtime', 'compile-time'].includes(kind)) return null
+    const members = [...new Set((value.members || []).map((item) => path(item)).filter(Boolean))].sort(compare).slice(0, 200)
+    const representativePath = (value.representativePath || []).map((item) => path(item)).filter(Boolean).slice(0, 201)
+    if (members.length < 2 || representativePath.length < 2) return null
+    return {id, kind, size: Math.max(int(value.size), members.length), members, membersTruncated: bool(value.membersTruncated) || int(value.size) > members.length, representativePath}
+}
+
+function boundaryFact(value) {
+    const ruleId = token(value?.ruleId, 96), from = path(value?.from), to = path(value?.to)
+    if (!ruleId || !from || !to || !['forbidden', 'allowedOnly'].includes(value?.kind) || !SEVERITIES.has(value?.severity)) return null
+    return {kind: value.kind, ruleId, severity: value.severity, from, to}
+}
+
+export function sanitizeArchitecture(value) {
+    const modules = list(value?.modules, CAPS.modules, moduleFact, (a, b) => compare(a.id, b.id))
+    const dependencies = {}
+    let truncated = modules.truncated
+    const dependencyMeta = {}
+    for (const kind of ['runtime', 'typeOnly', 'compileOnly']) {
+        const result = list(value?.dependencies?.[kind], CAPS.dependencies, dependency, (a, b) => compare(a.from, b.from) || compare(a.to, b.to))
+        dependencies[kind] = result.items
+        const completenessKey = `${kind}Dependencies`
+        dependencyMeta[completenessKey] = count(value?.completeness?.[completenessKey], result.total, result.items.length)
+        truncated ||= result.truncated
+    }
+    const cycles = list(value?.cycles, CAPS.findings, cycleFact, (a, b) => compare(a.kind, b.kind) || b.size - a.size || compare(a.id, b.id))
+    const boundaries = list(value?.boundaryViolations, CAPS.findings, boundaryFact, (a, b) => compare(a.ruleId, b.ruleId) || compare(a.from, b.from) || compare(a.to, b.to))
+    truncated ||= cycles.truncated || boundaries.truncated
+    const outState = state(value?.state)
+    return {
+        state: truncated && outState === 'COMPLETE' ? 'PARTIAL' : outState,
+        verdict: verdict(value?.verdict),
+        completeness: {modules: count(value?.completeness?.modules, modules.total, modules.items.length), ...dependencyMeta, cycles: count(value?.completeness?.cycles, cycles.total, cycles.items.length), boundaryViolations: count(value?.completeness?.boundaryViolations, boundaries.total, boundaries.items.length), reasons: reasons(value?.completeness?.reasons)},
+        modules: modules.items, dependencies, cycles: cycles.items, boundaryViolations: boundaries.items,
+        boundaryRulesState: state(value?.boundaryRulesState),
+    }
+}

package/src/mcp/sync/evidence-common.mjs

@@ -0,0 +1,88 @@
+export const SEVERITIES = new Set(['critical', 'high', 'medium', 'low', 'info'])
+export const CONFIDENCE = new Set(['high', 'medium', 'low'])
+export const CATEGORIES = new Set(['unused', 'structure', 'vulnerability', 'malware'])
+export const CHECK_KEYS = ['osv', 'malware']
+export const PACKAGE_DEPENDENCY_KINDS = new Set(['runtime', 'dev', 'optional', 'peer', 'optional-peer'])
+export const CAPS = Object.freeze({
+    modules: 500, dependencies: 2000, findings: 500, hotspots: 250, badges: 100,
+    packages: 5000, usage: 1000, files: 20, packageGraphNodes: 5000, packageGraphEdges: 20000,
+    duplicateGroups: 100, duplicateMembers: 12, divergenceCandidates: 100,
+})
+export const DUPLICATE_THRESHOLDS = Object.freeze({
+    clones: Object.freeze({mode: 'renamed', minSimilarityPercent: 80, minTokens: 50}),
+    divergence: Object.freeze({sameName: true, maxSimilarityPercent: 45, minTokens: 50, maxImplementationsPerName: 12}),
+})
+
+const STATES = new Set(['COMPLETE', 'PARTIAL', 'NOT_CHECKED', 'NOT_APPLICABLE', 'ERROR'])
+const VERDICTS = new Set(['PASS', 'FAIL', 'UNKNOWN'])
+const CONTROL = /[\u0000-\u001f\u007f]/
+const ABSOLUTE_PATH_FRAGMENT = /(?:^|[\/\s"'`(=])[a-z]:[\\/]|(?:^|[\s"'`(=])(?:\\\\[^\\/\s]+(?:[\\/]|$)|file:(?:\/\/)?[\\/]|\/(?!\/)[^\s])/i
+const TOKEN = /^[\p{L}\p{N}_.:@+\-#$<>()\[\],]+$/u
+const PACKAGE = /^(?:@[a-z0-9._-]+\/)?[a-z0-9][a-z0-9._-]*$/i
+
+export const int = (value) => Number.isFinite(value) && value >= 0 ? Math.trunc(value) : 0
+export const bool = (value) => value === true
+export const text = (value, max = 256) => typeof value === 'string' && value.length > 0 && value.length <= max && !CONTROL.test(value) ? value : undefined
+export const token = (value, max = 256) => { const valueText = text(value, max); return valueText && TOKEN.test(valueText) ? valueText : undefined }
+export const privacySafeText = (value, max = 256) => { const valueText = text(value, max); return valueText && !ABSOLUTE_PATH_FRAGMENT.test(valueText) ? valueText : undefined }
+export const packageName = (value) => { const valueText = text(value, 256); return valueText && PACKAGE.test(valueText) ? valueText : undefined }
+export const packageVersion = (value) => { const valueText = text(value, 128); return valueText && /^[A-Za-z0-9][A-Za-z0-9._+~-]*$/.test(valueText) ? valueText : undefined }
+export const state = (value) => STATES.has(value) ? value : 'ERROR'
+export const verdict = (value) => VERDICTS.has(value) ? value : 'UNKNOWN'
+export const compare = (a, b) => String(a).localeCompare(String(b), 'en')
+
+export function path(value, max = 4096) {
+    const raw = text(value, max)
+    if (!raw) return undefined
+    const normalized = raw.replace(/\\/g, '/')
+    if (/^(?:[a-z][a-z0-9+.-]*:|\/)/i.test(normalized)) return undefined
+    const parts = normalized.split('/')
+    return parts.length && parts.every((part) => part && part !== '.' && part !== '..') ? normalized : undefined
+}
+
+export function graphId(value) {
+    const id = text(value, 4096)
+    if (!id) return undefined
+    const hash = id.indexOf('#')
+    const file = hash < 0 ? id : id.slice(0, hash)
+    const safeFile = path(file)
+    if (!safeFile) return undefined
+    if (hash < 0) return safeFile
+    const suffix = id.slice(hash)
+    return suffix.length <= 512 && /^#[^\\/\s\u0000-\u001f\u007f]{1,511}$/u.test(suffix) ? `${safeFile}${suffix}` : undefined
+}
+
+export function moduleId(value) { return value === '(root)' ? value : path(value) }
+export function set(out, key, value) { if (value !== undefined) out[key] = value }
+
+export function stableStringify(value) {
+    if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`
+    if (value && typeof value === 'object') return `{${Object.keys(value).sort(compare).map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(',')}}`
+    return JSON.stringify(value)
+}
+
+export function list(values, cap, mapper, sorter) {
+    const all = (Array.isArray(values) ? values : []).map(mapper).filter(Boolean).sort(sorter)
+    return {items: all.slice(0, cap), total: all.length, truncated: all.length > cap}
+}
+
+export function count(value, fallbackTotal, returned) {
+    const total = Math.max(int(value?.total), fallbackTotal)
+    return {total, returned, truncated: bool(value?.truncated) || total > returned}
+}
+
+export function reasons(values) {
+    return [...new Set((Array.isArray(values) ? values : []).map((value) => token(value, 96)).filter(Boolean))].sort(compare).slice(0, 32)
+}
+
+export function numericRecord(value, keys) {
+    const out = {}
+    for (const key of keys) out[key] = int(value?.[key])
+    return out
+}
+
+export function checks(value) {
+    const out = {}
+    for (const key of CHECK_KEYS) out[key] = state(value?.[key])
+    return out
+}

package/src/mcp/sync/evidence-duplicates.mjs

@@ -0,0 +1,100 @@
+import {
+    CAPS, DUPLICATE_THRESHOLDS, bool, compare, count, graphId, int, list,
+    path, reasons, state, text, verdict,
+} from './evidence-common.mjs'
+
+function duplicateEvidenceId(value) {
+    const id = text(value, 64)
+    return id && /^[a-f0-9]{24,64}$/i.test(id) ? id : undefined
+}
+
+function duplicateMember(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return null
+    const file = path(value.file)
+    const startLine = int(value.startLine), endLine = int(value.endLine), tokens = int(value.tokens)
+    if (!file || startLine < 1 || endLine < startLine || tokens < DUPLICATE_THRESHOLDS.clones.minTokens) return null
+    const out = {file, startLine, endLine, tokens}
+    const nodeId = graphId(value.graphNodeId)
+    if (nodeId?.startsWith(`${file}#`)) out.graphNodeId = nodeId
+    return out
+}
+
+function compareDuplicateMember(a, b) {
+    return compare(a.file, b.file) || a.startLine - b.startLine || a.endLine - b.endLine || compare(a.graphNodeId || '', b.graphNodeId || '')
+}
+
+function duplicateMembers(values, cap = CAPS.duplicateMembers) {
+    const raw = Array.isArray(values) ? values : []
+    const unique = new Map()
+    for (const value of raw) {
+        const item = duplicateMember(value)
+        if (!item) continue
+        unique.set(`${item.file}\0${item.startLine}\0${item.endLine}\0${item.graphNodeId || ''}`, item)
+    }
+    const all = [...unique.values()].sort(compareDuplicateMember)
+    return {items: all.slice(0, cap), total: all.length, invalid: raw.length - all.length, truncated: all.length > cap}
+}
+
+function cloneGroup(value) {
+    const id = duplicateEvidenceId(value?.id)
+    const members = duplicateMembers(value?.members)
+    const rawStrongestSimilarity = Number(value?.strongestSimilarity)
+    const rawWeakestLinkedSimilarity = Number(value?.weakestLinkedSimilarity)
+    const strongestSimilarity = Math.trunc(rawStrongestSimilarity)
+    const weakestLinkedSimilarity = Math.trunc(rawWeakestLinkedSimilarity)
+    if (!id || members.items.length < 2 || strongestSimilarity < DUPLICATE_THRESHOLDS.clones.minSimilarityPercent ||
+        !Number.isFinite(rawStrongestSimilarity) || rawStrongestSimilarity > 100 ||
+        !Number.isFinite(rawWeakestLinkedSimilarity) || weakestLinkedSimilarity < DUPLICATE_THRESHOLDS.clones.minSimilarityPercent ||
+        rawWeakestLinkedSimilarity > 100 || weakestLinkedSimilarity > strongestSimilarity) return null
+    const memberCount = Math.max(int(value?.memberCount), members.total)
+    const returnedTokens = members.items.reduce((sum, member) => sum + member.tokens, 0)
+    return {
+        id, memberCount, totalTokens: Math.max(int(value?.totalTokens), returnedTokens),
+        strongestSimilarity, weakestLinkedSimilarity,
+        membersTruncated: bool(value?.membersTruncated) || members.truncated || members.invalid > 0 || memberCount > members.items.length,
+        members: members.items,
+    }
+}
+
+function divergenceCandidate(value) {
+    const id = duplicateEvidenceId(value?.id)
+    const symbol = text(value?.symbol, 256)
+    const rawSimilarity = Number(value?.similarity)
+    const similarity = Math.trunc(rawSimilarity)
+    const members = duplicateMembers(value?.members, 2)
+    if (!id || !symbol || !/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(symbol) || members.total !== 2 || members.invalid > 0 ||
+        !Number.isFinite(rawSimilarity) || rawSimilarity < 0 || rawSimilarity > DUPLICATE_THRESHOLDS.divergence.maxSimilarityPercent ||
+        members.items[0].file === members.items[1].file) return null
+    return {id, symbol, similarity, totalTokens: Math.max(int(value?.totalTokens), members.items[0].tokens + members.items[1].tokens), members: members.items}
+}
+
+export function sanitizeDuplicates(value) {
+    const rawGroups = Array.isArray(value?.cloneGroups) ? value.cloneGroups : []
+    const rawDivergence = Array.isArray(value?.divergenceCandidates) ? value.divergenceCandidates : []
+    const cloneGroups = list(rawGroups, CAPS.duplicateGroups, cloneGroup,
+        (a, b) => b.totalTokens - a.totalTokens || b.memberCount - a.memberCount || compare(a.id, b.id))
+    const divergence = list(rawDivergence, CAPS.divergenceCandidates, divergenceCandidate,
+        (a, b) => b.totalTokens - a.totalTokens || a.similarity - b.similarity || compare(a.symbol, b.symbol) || compare(a.id, b.id))
+    const invalid = rawGroups.length - cloneGroups.total + rawDivergence.length - divergence.total
+    const membersTruncated = cloneGroups.items.some((group) => group.membersTruncated)
+    const groupCompleteness = count(value?.completeness?.cloneGroups, rawGroups.length, cloneGroups.items.length)
+    const divergenceCompleteness = count(value?.completeness?.divergenceCandidates, rawDivergence.length, divergence.items.length)
+    const truncated = cloneGroups.truncated || divergence.truncated || groupCompleteness.truncated || divergenceCompleteness.truncated || membersTruncated || invalid > 0
+    const outReasons = reasons([
+        ...(Array.isArray(value?.completeness?.reasons) ? value.completeness.reasons : []),
+        ...(invalid > 0 ? ['INVALID_DUPLICATE_EVIDENCE_DROPPED'] : []),
+        ...(membersTruncated ? ['CLONE_MEMBERS_TRUNCATED'] : []),
+        ...(cloneGroups.truncated ? ['CLONE_GROUPS_TRUNCATED'] : []),
+        ...(divergence.truncated ? ['DIVERGENCE_CANDIDATES_TRUNCATED'] : []),
+    ])
+    const rawFragments = value?.completeness?.fragments
+    const eligible = int(rawFragments?.eligible), filtered = int(rawFragments?.filtered)
+    const total = Math.max(int(rawFragments?.total), eligible + filtered)
+    const outState = state(value?.state)
+    return {
+        state: truncated && outState === 'COMPLETE' ? 'PARTIAL' : outState,
+        verdict: verdict(value?.verdict), thresholds: DUPLICATE_THRESHOLDS,
+        completeness: {fragments: {total, eligible: Math.min(eligible, total), filtered: Math.max(filtered, total - eligible)}, cloneGroups: groupCompleteness, divergenceCandidates: divergenceCompleteness, reasons: outReasons},
+        cloneGroups: cloneGroups.items, divergenceCandidates: divergence.items,
+    }
+}