weavatrix 0.1.4 → 0.2.0

package/src/graph/repo-registry.js

@@ -0,0 +1,124 @@
+// Global local registry for repository graphs. Absolute paths never leave the machine; hosted sync
+// uses the opaque UUID. Identity is anchored in each canonical graph folder so simultaneous MCP
+// processes cannot mint different IDs for the same repository.
+import {randomUUID} from 'node:crypto'
+import {existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync} from 'node:fs'
+import {basename, join, relative, resolve} from 'node:path'
+import process from 'node:process'
+import {graphStorageKey} from './layout.js'
+import {atomicWriteFileSync, withFileLockSync} from './file-lock.js'
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+const MARKER = '.repository-id'
+
+const normalized = (value) => {
+    const path = String(value || '').replace(/\\/g, '/').replace(/\/+$/, '')
+    return process.platform === 'win32' ? path.toLowerCase() : path
+}
+
+const realOrResolved = (value) => {
+    try { return realpathSync.native(value) } catch { return resolve(value) }
+}
+
+const canonicalGraphDir = (repoPath, graphHome) => join(resolve(graphHome), graphStorageKey(repoPath))
+const markerPath = (graphDir) => join(graphDir, MARKER)
+
+export function registryPath(graphHome) { return join(graphHome, 'repositories.json') }
+
+export function readRepositoryRegistry(graphHome) {
+    try {
+        const parsed = JSON.parse(readFileSync(registryPath(graphHome), 'utf8'))
+        return parsed?.repositoryRegistryV === 1 && Array.isArray(parsed.repositories)
+            ? parsed.repositories.filter((item) => item && typeof item === 'object')
+            : []
+    } catch { return [] }
+}
+
+function writeRegistry(graphHome, repositories) {
+    atomicWriteFileSync(registryPath(graphHome), JSON.stringify({repositoryRegistryV: 1, repositories}, null, 2), 'utf8')
+}
+
+function readMarker(graphDir) {
+    try {
+        const id = readFileSync(markerPath(graphDir), 'utf8').trim()
+        return UUID.test(id) ? id : null
+    } catch { return null }
+}
+
+function createOrReadMarker(graphDir, preferredId) {
+    mkdirSync(graphDir, {recursive: true})
+    const path = markerPath(graphDir)
+    const existing = readMarker(graphDir)
+    if (existing) return existing
+    if (existsSync(path)) throw new Error(`invalid repository identity marker: ${path}`)
+    const candidate = UUID.test(String(preferredId || '')) ? preferredId : randomUUID()
+    try { writeFileSync(path, `${candidate}\n`, {encoding: 'utf8', flag: 'wx'}) }
+    catch (error) {
+        if (error?.code !== 'EEXIST') throw error
+        const raced = readMarker(graphDir)
+        if (!raced) throw new Error(`invalid repository identity marker after concurrent registration: ${path}`)
+        return raced
+    }
+    return candidate
+}
+
+export function registerRepository({repoPath, graphDir, graphHome}) {
+    mkdirSync(graphHome, {recursive: true})
+    const real = realOrResolved(repoPath)
+    const canonical = canonicalGraphDir(real, graphHome)
+    if (normalized(realOrResolved(graphDir)) !== normalized(realOrResolved(canonical))) {
+        throw new Error(`repository graphs must be registered from the canonical graph directory: ${canonical}`)
+    }
+    return withFileLockSync(join(graphHome, '.repositories.lock'), () => {
+        const key = normalized(real)
+        const repositories = readRepositoryRegistry(graphHome)
+        let record = repositories.find((item) => normalized(item.repoPath) === key)
+        const now = new Date().toISOString()
+        const repositoryId = createOrReadMarker(canonical, record?.repositoryId)
+        if (!record) {
+            record = {repositoryId, repoPath: real, label: basename(real) || 'repo', graphDir: canonical, firstSeenAt: now, lastSeenAt: now}
+            repositories.push(record)
+        } else {
+            record.repositoryId = repositoryId
+            record.repoPath = real
+            record.graphDir = canonical
+            record.label = basename(real) || record.label || 'repo'
+            record.lastSeenAt = now
+        }
+        const deduped = repositories.filter((item, index, all) =>
+            normalized(item.repoPath) !== key || all.findIndex((candidate) => normalized(candidate.repoPath) === key) === index)
+        deduped.sort((a, b) => String(a.label).localeCompare(String(b.label)) || String(a.repositoryId).localeCompare(String(b.repositoryId)))
+        writeRegistry(graphHome, deduped)
+        return {...record}
+    })
+}
+
+export function repositoryRecord(repoPath, graphHome) {
+    const real = realOrResolved(repoPath)
+    const key = normalized(real)
+    return liveRepositoryRecords(graphHome).find((item) => normalized(item.repoPath) === key) || null
+}
+
+function validLiveRecord(item, graphHome) {
+    if (!UUID.test(String(item?.repositoryId || '')) || typeof item?.repoPath !== 'string' || typeof item?.graphDir !== 'string') return null
+    let repoReal
+    let graphHomeReal
+    let graphReal
+    try {
+        repoReal = realpathSync.native(item.repoPath)
+        graphHomeReal = realpathSync.native(graphHome)
+        graphReal = realpathSync.native(item.graphDir)
+        if (!statSync(repoReal).isDirectory() || !existsSync(join(repoReal, '.git'))) return null
+        if (!statSync(graphReal).isDirectory() || !statSync(join(graphReal, 'graph.json')).isFile()) return null
+    } catch { return null }
+    if (normalized(graphReal) !== normalized(realOrResolved(canonicalGraphDir(repoReal, graphHomeReal)))) return null
+    const rel = relative(graphHomeReal, graphReal)
+    if (!rel || rel.startsWith('..') || resolve(graphHomeReal, rel) !== resolve(graphReal)) return null
+    if (readMarker(graphReal) !== item.repositoryId) return null
+    return {...item, repoPath: repoReal, graphDir: graphReal}
+}
+
+export function liveRepositoryRecords(graphHome) {
+    if (!existsSync(graphHome)) return []
+    return readRepositoryRegistry(graphHome).map((item) => validLiveRecord(item, graphHome)).filter(Boolean)
+}

package/src/mcp/catalog.mjs

@@ -11,53 +11,96 @@ import {readSource, searchCode} from '../mcp-source-tools.mjs'
 
 const SELF_DIR = dirname(fileURLToPath(import.meta.url))
 const resolveRg = createRgResolver(SELF_DIR)
-export const DEFAULT_CAPS = Object.freeze(['graph', 'search', 'source', 'health', 'build', 'retarget'])
+// The default profile is fully offline and includes explicit local repository retargeting. Operators
+// who want a hard single-repository boundary can select the `pinned` profile instead. HTTP tools are
+// split into explicit `advisories` and `hosted` capabilities; the old `online` name remains an alias
+// for both so existing registrations keep working.
+export const DEFAULT_CAPS = Object.freeze(['graph', 'search', 'source', 'health', 'build', 'retarget', 'crossrepo'])
+const PROFILE_CAPS = Object.freeze({
+    offline: DEFAULT_CAPS,
+    pinned: ['graph', 'search', 'source', 'health', 'build'],
+    osv: [...DEFAULT_CAPS, 'advisories'],
+    hosted: [...DEFAULT_CAPS, 'advisories', 'hosted'],
+    full: [...DEFAULT_CAPS, 'advisories', 'hosted'],
+})
 
 // The files whose mtime the stdio shell watches for hot reload — keep in sync with the imports in
 // loadHotApi below (catalog.mjs itself is last: a change here re-derives the whole table).
-export const HOT_FILES = ['tools-graph.mjs', 'tools-impact.mjs', 'tools-health.mjs', 'tools-actions.mjs', 'catalog.mjs']
+export const HOT_FILES = ['tools-graph.mjs', 'tools-impact.mjs', 'tools-health.mjs', 'tools-actions.mjs', 'tools-architecture.mjs', 'tools-history.mjs', 'tools-company.mjs', 'catalog.mjs']
 
-function buildTools({tg, ti, th, ta}) {
-    return [
+function buildTools({tg, ti, th, ta, tar, thi, tc}) {
+    const tools = [
         {cap: 'graph', name: 'graph_stats', description: 'Return summary statistics: node count, edge count, communities, confidence breakdown, and graph build time vs repo HEAD (staleness).', inputSchema: {type: 'object', properties: {}}, run: (g, a, ctx) => tg.tGraphStats(g, ctx)},
         {cap: 'graph', name: 'get_node', description: 'Get full details for a specific node by label or ID.', inputSchema: {type: 'object', properties: {label: {type: 'string', description: 'Node label or ID to look up'}}, required: ['label']}, run: (g, a, ctx) => tg.tGetNode(g, a, ctx)},
         {cap: 'graph', name: 'get_neighbors', description: 'Get all direct neighbors of a node with edge details (1 hop, call sites deduped). For transitive impact use get_dependents; for the impact of your current branch changes use change_impact.', inputSchema: {type: 'object', properties: {label: {type: 'string'}, relation_filter: {type: 'string', description: 'Optional: filter by relation type'}}, required: ['label']}, run: (g, a, ctx) => tg.tGetNeighbors(g, a, ctx)},
-        {cap: 'graph', name: 'query_graph', description: 'Explore the graph around a concept (BFS/DFS). Returns a focused, ranked subgraph — the closest, most-connected nodes near the matched seeds, with edges among them — not the full flood; states how many nodes were reached vs shown.', inputSchema: {type: 'object', properties: {question: {type: 'string', description: 'Natural language question or keyword search'}, mode: {type: 'string', enum: ['bfs', 'dfs'], default: 'bfs'}, depth: {type: 'integer', default: 3}, context_filter: {type: 'array', items: {type: 'string'}}, token_budget: {type: 'integer', description: 'Higher budget shows more nodes/edges', default: 2000}}, required: ['question']}, run: (g, a) => tg.tQueryGraph(g, a)},
+        {cap: 'graph', name: 'query_graph', description: 'Explore the graph around a concept (BFS/DFS). Returns a focused, ranked subgraph — the closest, most-connected nodes near the matched seeds, with edges among them — not the full flood; states how many nodes were reached vs shown.', inputSchema: {type: 'object', properties: {question: {type: 'string', description: 'Natural language question or keyword search'}, mode: {type: 'string', enum: ['bfs', 'dfs'], default: 'bfs'}, depth: {type: 'integer', default: 3}, context_filter: {type: 'array', items: {type: 'string'}}, seed_files: {type: 'array', items: {type: 'string'}, maxItems: 12, description: 'Optional exact repo-relative file paths. When resolved, these are the only seeds unless augment_seeds is true'}, augment_seeds: {type: 'boolean', default: false, description: 'With seed_files, also add fuzzy question-derived seeds; false keeps traversal strictly pinned'}, token_budget: {type: 'integer', description: 'Higher budget shows more nodes/edges', default: 2000}}, required: ['question']}, run: (g, a) => tg.tQueryGraph(g, a)},
         {cap: 'graph', name: 'god_nodes', description: 'Rank connectivity hubs by unique call/import/reference neighbors, with class/method ownership reported separately from runtime connectivity. Repeated call sites do not inflate the rank.', inputSchema: {type: 'object', properties: {top_n: {type: 'integer', default: 10}}}, run: (g, a) => tg.tGodNodes(g, a)},
         {cap: 'graph', name: 'shortest_path', description: 'Find the shortest path between two concepts in the knowledge graph.', inputSchema: {type: 'object', properties: {source: {type: 'string'}, target: {type: 'string'}, max_hops: {type: 'integer', default: 8}}, required: ['source', 'target']}, run: (g, a) => tg.tShortestPath(g, a)},
         {cap: 'graph', name: 'get_dependents', description: 'Transitive blast-radius of ONE node: everything that calls/imports/inherits it, directly or through intermediaries (reverse edges, ranked by proximity then connectivity). For a symbol, also follows importers of its containing file. Use before refactoring; get_neighbors shows only 1 hop, change_impact covers your whole current diff at once.', inputSchema: {type: 'object', properties: {label: {type: 'string', description: 'Node label or ID'}, depth: {type: 'integer', description: 'Max reverse hops, default 3', default: 3}, max_nodes: {type: 'integer', description: 'Max dependents to list, default 40', default: 40}}, required: ['label']}, run: (g, a) => ti.tGetDependents(g, a)},
-        {cap: 'graph', name: 'change_impact', description: 'Blast radius of a change: by default diffs branch commits + staged/unstaged/untracked work against a base ref (auto merge-base with origin/main|master), OR takes an explicit `files` list (e.g. a PR\'s changed files — assesses a NOT-checked-out PR). Maps changed files/symbols onto the graph and lists everything depending on them (reverse edges, ranked by proximity + connectivity) with test coverage attached — untested hotspots called out. Run before opening or reviewing a PR; drill down with get_dependents, coverage detail via coverage_map.', inputSchema: {type: 'object', properties: {base: {type: 'string', description: 'Base ref, e.g. origin/main or HEAD~1 (default: first existing of origin/HEAD, origin/main, origin/master, main, master)'}, files: {type: 'array', items: {type: 'string'}, description: 'Explicit repo-relative changed-file list — skips the local git diff; use for PRs that are not checked out'}, depth: {type: 'integer', description: 'Max reverse hops, default 2'}, max_nodes: {type: 'integer', description: 'Max impacted nodes to list, default 40'}}}, run: (g, a, ctx) => ti.tChangeImpact(g, a, ctx)},
+        {cap: 'graph', name: 'change_impact', description: 'Verdict-first, symbol-aware blast radius. Parses a zero-context git diff, distinguishes additive exports from signature/body/removal risk, and reverse-traverses only exact changed seeds so a new API does not inherit every legacy importer of its file. Measured coverage is used when present; otherwise static test reachability is labelled actualCoverage=NOT_AVAILABLE. Pass `diff` for a not-checked-out PR; `files` without a diff remains a conservative fallback.', inputSchema: {type: 'object', properties: {base: {type: 'string', description: 'Base ref, e.g. origin/main or HEAD~1 (default: first existing of origin/HEAD, origin/main, origin/master, main, master)'}, diff: {type: 'string', maxLength: 2097152, description: 'Optional unified diff (prefer --unified=0) for a PR/change that is not checked out; enables symbol-level classification'}, files: {type: 'array', items: {type: 'string'}, maxItems: 500, description: 'Optional repo-relative changed-file hints. Without diff evidence these are classified conservatively rather than guessed additive'}, depth: {type: 'integer', description: 'Max reverse hops, default 2'}, max_nodes: {type: 'integer', description: 'Max impacted nodes to list, default 40'}}}, run: (g, a, ctx) => ti.tChangeImpact(g, a, ctx)},
+        {cap: 'graph', name: 'git_history', description: 'Behavioral architecture evidence from bounded local git history: churn × connectivity hotspots, hidden co-change coupling, and expected test/source coupling. Reads numstat only — never commit messages, authors, or source bodies.', inputSchema: {type: 'object', properties: {months: {type: 'integer', enum: [3, 6, 12], default: 6}, max_commits: {type: 'integer', minimum: 1, maximum: 5000, default: 1000}, min_pair_count: {type: 'integer', minimum: 2, maximum: 100, default: 3}, max_pairs: {type: 'integer', minimum: 1, maximum: 500, default: 100}, top_n: {type: 'integer', minimum: 1, maximum: 50, default: 10}}}, run: (g, a, ctx) => thi.tGitHistory(g, a, ctx)},
+        {cap: 'crossrepo', name: 'trace_api_contract', description: 'Cross-repository HTTP contract and blast-radius evidence. Select a registered backend and one or more registered clients by stable repository UUID or unambiguous label; joins backend endpoints to static client calls and follows client importers to affected screens. Repository paths stay local and cannot be supplied through this tool. This capability is intentionally absent from the pinned profile.', inputSchema: {type: 'object', properties: {backend: {type: 'string', description: 'Backend repository UUID or exact unambiguous registry label'}, clients: {type: 'array', items: {type: 'string'}, minItems: 1, maxItems: 20, description: 'Client repository UUIDs or exact unambiguous registry labels'}, method: {type: 'string', enum: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']}, path: {type: 'string', maxLength: 2048, description: 'Optional endpoint route filter; {id}, :id and concrete parameter values are normalized'}, changed_files: {type: 'array', items: {type: 'string'}, maxItems: 500, description: 'Optional backend repo-relative changed files; only endpoints declared in those files are traced'}, include_tests: {type: 'boolean', default: false}, max_impact_depth: {type: 'integer', minimum: 0, maximum: 5, default: 2}, max_endpoints: {type: 'integer', minimum: 1, maximum: 500, default: 250}, max_matches: {type: 'integer', minimum: 1, maximum: 5000, default: 1000}, max_affected_files: {type: 'integer', minimum: 1, maximum: 500, default: 100}, top_n: {type: 'integer', minimum: 1, maximum: 50, default: 10}}, required: ['backend', 'clients']}, run: (g, a, ctx) => tc.tTraceApiContract(g, a, ctx)},
         {cap: 'graph', name: 'get_community', description: 'Get all nodes in a community by community ID (0-indexed by size).', inputSchema: {type: 'object', properties: {community_id: {type: 'integer', description: 'Community ID (0-indexed by size)'}}, required: ['community_id']}, run: (g, a) => tg.tGetCommunity(g, a)},
         {cap: 'search', name: 'search_code', description: 'Full-text or regex search across the repo source (ripgrep-backed, Node fallback). The graph only stores structure — use this to find literal text/patterns, then get_node/get_neighbors for structure.', inputSchema: {type: 'object', properties: {query: {type: 'string', description: 'text or regex to search for'}, is_regex: {type: 'boolean', default: false}, glob: {type: 'string', description: 'optional path glob, e.g. "*.js" or "src/**"'}, max_results: {type: 'integer', default: 40}}, required: ['query']}, run: (g, a, ctx) => searchCode({repoRoot: ctx.repoRoot, resolveRg}, a)},
         {cap: 'source', name: 'read_source', description: "Read the actual source of a node (by label/ID) or a repo-relative file path — the symbol's lines with context. The graph stores only locations, not source text. For a path read, pass start_line to anchor the window anywhere in the file (otherwise it shows the head).", inputSchema: {type: 'object', properties: {label: {type: 'string', description: 'node label or ID'}, path: {type: 'string', description: 'or a repo-relative file path'}, start_line: {type: 'integer', description: 'anchor line: window = start_line-before .. start_line+after'}, before: {type: 'integer', default: 3}, after: {type: 'integer', default: 40}}}, run: (g, a, ctx) => readSource({repoRoot: ctx.repoRoot, resolveNode, isSymbol}, g, a)},
-        {cap: 'health', name: 'find_duplicates', description: "Content-based clone detection over the repo (MOSS winnowing over method bodies — finds copy-paste even with renamed variables, not just matching names). Returns clone groups with file:line sites. Use to guide de-duplication refactors. mode 'semantic' flips the lens: same-name symbols across files ranked by size, where LOW similarity marks divergent copies (same name, drifted behavior) — min_similarity is ignored there.", inputSchema: {type: 'object', properties: {min_similarity: {type: 'integer', description: '50-100, default 80 (ignored in semantic mode)'}, min_tokens: {type: 'integer', description: 'min fragment size, default 50'}, mode: {type: 'string', enum: ['renamed', 'strict', 'semantic'], default: 'renamed'}, include_tests: {type: 'boolean', default: false}, include_strings: {type: 'boolean', description: 'Also clone-check large multi-line string literals (embedded C#/SQL/PowerShell templates) — the code pass strips string bodies, so these are otherwise invisible', default: false}, top_n: {type: 'integer', default: 15}}}, run: (g, a, ctx) => th.tFindDuplicates(g, a, ctx)},
-        {cap: 'health', name: 'run_audit', description: 'Full internal health audit of the repo: dead code (unused files/exports), dependency health (missing/undeclared and unused npm/Go/Python deps), structure (import cycles, orphan files, boundary-rule violations), and offline supply-chain checks (known OSV vulnerabilities, typosquats, lockfile drift). Filter by category/severity. Malware heuristics are opt-in (slow).', inputSchema: {type: 'object', properties: {category: {type: 'string', enum: ['unused', 'structure', 'vulnerability', 'malware'], description: 'Only findings of this category'}, min_severity: {type: 'string', enum: ['critical', 'high', 'medium', 'low', 'info'], description: 'Minimum severity to include'}, max_findings: {type: 'integer', description: 'Max findings to list, default 30'}, include_malware_scan: {type: 'boolean', description: 'Also grep installed packages for malware heuristics (slow)', default: false}}}, run: (g, a, ctx) => th.tRunAudit(g, a, ctx)},
-        {cap: 'health', name: 'coverage_map', description: 'Map an existing test-coverage report (istanbul/lcov/coverage.py/Go cover.out — read offline, never runs tests) onto the code graph: per-module coverage plus refactor-risk hotspots — well-connected symbols with low coverage, ranked by degree × uncovered. Pair with get_dependents: many dependents + low coverage ⇒ write tests before changing.', inputSchema: {type: 'object', properties: {top_n: {type: 'integer', description: 'Max risk hotspots to list, default 15'}, path: {type: 'string', description: 'Optional repo-relative path prefix filter, e.g. src/query'}}}, run: (g, a, ctx) => th.tCoverageMap(g, a, ctx)},
+        {cap: 'health', name: 'find_duplicates', description: "Content-based clone detection over production code (MOSS winnowing over method bodies). Tests, e2e, generated code, mocks, stories, docs, benchmarks and temporary roots are classified separately and excluded by default; opt them in explicitly.", inputSchema: {type: 'object', properties: {min_similarity: {type: 'integer', description: '50-100, default 80 (ignored in semantic mode)'}, min_tokens: {type: 'integer', description: 'min fragment size, default 50'}, mode: {type: 'string', enum: ['renamed', 'strict', 'semantic'], default: 'renamed'}, include_tests: {type: 'boolean', default: false}, include_classified: {type: 'boolean', default: false, description: 'Include generated/mock/story/docs/benchmark/temp and paths explicitly classified as excluded; tests still require include_tests'}, include_strings: {type: 'boolean', description: 'Also clone-check large multi-line string literals', default: false}, top_n: {type: 'integer', default: 15}}}, run: (g, a, ctx) => th.tFindDuplicates(g, a, ctx)},
+        {cap: 'health', name: 'find_dead_code', description: 'Conservative review queue for statically unreferenced files, functions, methods and symbols. Returns confidence, reason, bounded evidence and explicit framework/dynamic/reflection/public-API caveats; never an auto-delete verdict. Tests, generated code, mocks, stories, docs, benchmarks and temporary roots are excluded by default.', inputSchema: {type: 'object', properties: {path: {type: 'string', maxLength: 1024, description: 'Optional repo-relative path prefix'}, kinds: {type: 'array', items: {type: 'string', enum: ['file', 'function', 'method', 'symbol']}, maxItems: 4, uniqueItems: true, description: 'Optional candidate kinds; defaults to all'}, min_confidence: {type: 'string', enum: ['high', 'medium', 'low'], default: 'medium', description: 'Minimum confidence to include. low explicitly includes public/framework/dynamic review candidates'}, include_tests: {type: 'boolean', default: false}, include_classified: {type: 'boolean', default: false, description: 'Include generated/mock/story/docs/benchmark/temp and paths explicitly classified as excluded; tests still require include_tests'}, top_n: {type: 'integer', minimum: 1, maximum: 100, default: 30}}}, run: (g, a, ctx) => th.tFindDeadCode(g, a, ctx)},
+        {cap: 'health', name: 'run_audit', description: 'Full internal health audit. With base_ref, builds and audits an immutable Git checkout, derives changed files, and compares stable deterministic finding IDs; debt defaults to genuinely new findings. Supply-chain checks remain explicitly uncomparable across the source-only baseline. changed_files without base_ref is only changed-scope, never a new-debt claim.', inputSchema: {type: 'object', properties: {category: {type: 'string', enum: ['unused', 'structure', 'vulnerability', 'malware'], description: 'Only findings of this category'}, min_severity: {type: 'string', enum: ['critical', 'high', 'medium', 'low', 'info'], description: 'Minimum severity to include'}, max_findings: {type: 'integer', description: 'Max findings to list, default 30'}, include_malware_scan: {type: 'boolean', description: 'Also grep installed packages for malware heuristics (slow)', default: false}, base_ref: {type: 'string', maxLength: 200, description: 'Optional immutable Git baseline (for example HEAD~1 or origin/main). Enables honest new/existing/fixed debt comparison'}, changed_files: {type: 'array', items: {type: 'string'}, minItems: 1, maxItems: 500, description: 'Optional explicit repo-relative scope. Without base_ref this is changed-scope only; when omitted with base_ref, files are derived from the Git diff'}, debt: {type: 'string', enum: ['new', 'existing', 'all'], default: 'new', description: 'Baseline comparison view. Defaults to genuinely new deterministic findings when base_ref is present'}}}, run: (g, a, ctx) => th.tRunAudit(g, a, ctx)},
+        {cap: 'health', name: 'coverage_map', description: 'Map a real existing coverage report onto the graph. If no report exists, return clearly labelled static test reachability (a test imports/reaches a source file) with actualCoverage=NOT_AVAILABLE; reachability is never presented as measured coverage.', inputSchema: {type: 'object', properties: {top_n: {type: 'integer', description: 'Max risk hotspots to list, default 15'}, path: {type: 'string', description: 'Optional repo-relative path prefix filter, e.g. src/query'}}}, run: (g, a, ctx) => th.tCoverageMap(g, a, ctx)},
         {cap: 'graph', name: 'list_communities', description: 'List graph communities named by their dominant folder (largest first) with sample files — a readable module overview; feed the list position into get_community.', inputSchema: {type: 'object', properties: {top_n: {type: 'integer', description: 'Max communities to list, default 20'}}}, run: (g, a, ctx) => th.tListCommunities(g, a, ctx)},
         {cap: 'graph', name: 'module_map', description: 'Folder-level architecture map with file/symbol counts and strongest module dependencies, separating runtime, TypeScript type-only and language compile-only coupling.', inputSchema: {type: 'object', properties: {top_n: {type: 'integer', description: 'Max modules to list, default 25'}}}, run: (g, a, ctx) => th.tModuleMap(g, a, ctx)},
-        {cap: 'source', name: 'list_endpoints', description: 'Inventory of HTTP endpoints defined in the repo (Express/Fastify/Nest/Flask/FastAPI/Go mux/Rust axum and actix-web …): method, path, handler, and file:line.', inputSchema: {type: 'object', properties: {max_results: {type: 'integer', description: 'Max endpoints to list, default 100'}}}, run: (g, a, ctx) => th.tListEndpoints(g, a, ctx)},
-        {cap: 'build', name: 'rebuild_graph', description: "Rebuild this repo's code graph from current source (weavatrix's own web-tree-sitter builder), reload it in-memory, and report the STRUCTURAL DELTA vs the previous state — new/removed module dependencies, cycle changes, newly orphaned symbols. The prior state is saved as graph.prev.json for graph_diff. Call after significant edits.", inputSchema: {type: 'object', properties: {mode: {type: 'string', enum: ['full', 'no-tests', 'tests-only'], default: 'full'}, scope: {type: 'string', description: 'optional path prefix to limit the graph'}}}, run: (g, a, ctx) => ta.tRebuildGraph(g, a, ctx)},
-        {cap: 'graph', name: 'graph_diff', description: 'Structural diff of the last rebuild: previous graph state (graph.prev.json, saved by rebuild_graph) vs current — architecture drift (new module dependencies), broken or introduced import cycles, symbols that lost their last caller. The semantic complement to the textual git diff for validating a refactor.', inputSchema: {type: 'object', properties: {path: {type: 'string', description: 'Optional node-id/path prefix to scope the diff, e.g. src/query'}}}, run: (g, a, ctx) => ti.tGraphDiff(g, a, ctx)},
+        {cap: 'source', refreshGraph: true, name: 'list_endpoints', description: 'Inventory of HTTP endpoints defined in the repo (Express/Fastify/Nest/Flask/FastAPI/Go mux/Rust axum and actix-web/Spring MVC and WebFlux): method, composed path, handler, and file:line.', inputSchema: {type: 'object', properties: {max_results: {type: 'integer', description: 'Max endpoints to list, default 100'}}}, run: (g, a, ctx) => th.tListEndpoints(g, a, ctx)},
+        {cap: 'build', name: 'rebuild_graph', description: "Rebuild the active full-repository graph and report a structural delta. With scope, build an isolated diagnostic graph without replacing or diffing the full graph; normal graph queries remain pinned to the full repository.", inputSchema: {type: 'object', properties: {mode: {type: 'string', enum: ['full', 'no-tests', 'tests-only'], default: 'full'}, scope: {type: 'string', description: 'Optional isolated diagnostic path prefix; never replaces the active full graph'}}}, run: (g, a, ctx) => ta.tRebuildGraph(g, a, ctx)},
+        {cap: 'graph', name: 'graph_diff', description: 'Structural graph diff: compare the current graph with an immutable Git-ref baseline (base_ref such as HEAD~1 or main), or with graph.prev.json from the last rebuild when base_ref is omitted. Reports architecture drift, cycle changes and symbols that lost their last caller.', inputSchema: {type: 'object', properties: {base_ref: {type: 'string', maxLength: 256, description: 'Optional immutable Git baseline to build in isolation, e.g. HEAD~1, main or origin/main; never checks out or mutates the working tree'}, path: {type: 'string', description: 'Optional node-id/path prefix to scope the diff, e.g. src/query'}}}, run: (g, a, ctx) => ti.tGraphDiff(g, a, ctx)},
+        {cap: 'graph', name: 'get_architecture_contract', description: 'Return the executable target-architecture contract, quality budgets and ratchet mode that an agent must follow before editing.', inputSchema: {type: 'object', properties: {}}, run: (g, a, ctx) => tar.tGetArchitectureContract(g, a, ctx)},
+        {cap: 'graph', name: 'prepare_change', description: 'Select active target-architecture rules for an intended set of changed files. Run before a non-trivial edit.', inputSchema: {type: 'object', properties: {intent: {type: 'string'}, files: {type: 'array', items: {type: 'string'}, maxItems: 200}}, required: ['files']}, run: (g, a, ctx) => tar.tPrepareChange(g, a, ctx)},
+        {cap: 'health', name: 'verify_architecture', description: 'Verify the fresh graph against the active target contract and ratchet; separates new, existing, fixed and excepted debt.', inputSchema: {type: 'object', properties: {}}, run: (g, a, ctx) => tar.tVerifyArchitecture(g, a, ctx)},
+        {cap: 'health', name: 'explain_architecture_violation', description: 'Explain one active architecture violation and the governing rule.', inputSchema: {type: 'object', properties: {fingerprint: {type: 'string'}}, required: ['fingerprint']}, run: (g, a, ctx) => tar.tExplainArchitectureViolation(g, a, ctx)},
+        {cap: 'health', name: 'propose_architecture_exception', description: 'Prepare, but never apply, a bounded exception proposal for human review.', inputSchema: {type: 'object', properties: {fingerprint: {type: 'string'}, reason: {type: 'string'}, expires: {type: 'string', description: 'Optional YYYY-MM-DD'}}, required: ['fingerprint', 'reason']}, run: (g, a, ctx) => tar.tProposeArchitectureException(g, a, ctx)},
         {cap: 'retarget', name: 'open_repo', description: 'OFFLINE RETARGET: switch this server to another local Git repository, building its graph when missing. This explicit tool call changes the active repository boundary; pass build:false to probe without building. Omit the retarget capability at registration to pin one repository.', inputSchema: {type: 'object', properties: {path: {type: 'string', description: 'Absolute path to a Git working tree'}, build: {type: 'boolean', description: 'Build the graph when missing (default true)', default: true}, mode: {type: 'string', enum: ['full', 'no-tests', 'tests-only'], default: 'full'}}, required: ['path']}, run: (g, a, ctx) => ta.tOpenRepo(g, a, ctx)},
-        {cap: 'retarget', name: 'list_known_repos', description: 'OFFLINE RETARGET: list sibling repositories with existing graphs that can be selected through open_repo.', inputSchema: {type: 'object', properties: {}}, run: (g, a, ctx) => ta.tListKnownRepos(g, a, ctx)},
-        {cap: 'online', name: 'refresh_advisories', description: "ONLINE, explicit opt-in: refresh the local OSV advisory store for this repo's lockfile-pinned packages (npm/PyPI/Go). Sends package names + versions to OSV.dev — never automatic, never source code. Afterwards run_audit reads the refreshed store fully offline (~/.weavatrix/advisories.json).", inputSchema: {type: 'object', properties: {timeout_ms: {type: 'integer', description: 'Per-request timeout, default 20000'}}}, run: (g, a, ctx) => ta.tRefreshAdvisories(g, a, ctx)},
-        {cap: 'online', name: 'sync_graph', description: 'ONLINE, explicit opt-in, off until configured: send a versioned allowlist of graph metadata to an endpoint you configure (env WEAVATRIX_SYNC_URL, optional WEAVATRIX_SYNC_TOKEN bearer auth). Unknown graph fields are discarded and source file bodies are never read for sync. Rebuild graphs created before 0.1.4 once to add edge metadata v2.', inputSchema: {type: 'object', properties: {}}, run: (g, a, ctx) => ta.tSyncGraph(g, a, ctx)},
+        {cap: 'retarget', name: 'list_known_repos', description: 'OFFLINE RETARGET: list every registered local repository graph from the global per-user registry, regardless of parent folder.', inputSchema: {type: 'object', properties: {}}, run: (g, a, ctx) => ta.tListKnownRepos(g, a, ctx)},
+        {cap: 'advisories', name: 'refresh_advisories', description: "NETWORK / explicit advisories profile: refresh the local OSV advisory store for this repo's lockfile-pinned packages (npm/PyPI/Go). Sends package names + versions to OSV.dev — never automatic, never source code. Afterwards run_audit reads the refreshed store fully offline (~/.weavatrix/advisories.json).", inputSchema: {type: 'object', properties: {timeout_ms: {type: 'integer', description: 'Per-request timeout, default 20000'}}}, run: (g, a, ctx) => ta.tRefreshAdvisories(g, a, ctx)},
+        {cap: 'hosted', name: 'pull_architecture_contract', description: 'NETWORK / explicit hosted profile: fetch the owner-approved target architecture for the active stable repository UUID, validate it and cache it locally. Sends only the opaque UUID with bearer auth; never source or paths.', inputSchema: {type: 'object', properties: {timeout_ms: {type: 'integer', minimum: 1000, maximum: 120000, default: 30000}}}, run: (g, a, ctx) => ta.tPullArchitectureContract(g, a, ctx)},
+        {cap: 'hosted', name: 'sync_graph', description: 'NETWORK / explicit hosted profile, off until configured: derive a bounded evidence snapshot locally and send it with an allowlisted graph payload to an endpoint you configure (env WEAVATRIX_SYNC_URL, WEAVATRIX_SYNC_TOKEN bearer auth). Local analyzers may read source files, but file bodies, snippets, absolute paths and unknown fields are never uploaded. Payload v3 includes architecture/health/stack/package evidence; request v2 only for graph-only compatibility.', inputSchema: {type: 'object', properties: {payload_version: {type: 'integer', enum: [2, 3], default: 3, description: '3 includes the evidence snapshot; 2 is graph-only compatibility and is never selected as a silent fallback'}, timeout_ms: {type: 'integer', minimum: 1000, maximum: 120000, default: 30000, description: 'Network timeout in milliseconds'}}}, run: (g, a, ctx) => ta.tSyncGraph(g, a, ctx)},
     ]
+    // Every tool supports the same machine-output switch. structuredContent is returned regardless;
+    // output_format=json mirrors that envelope into TextContent for older workflow runners.
+    return tools.map((tool) => ({
+        ...tool,
+        inputSchema: {
+            ...(tool.inputSchema || {type: 'object'}),
+            properties: {
+                ...(tool.inputSchema?.properties || {}),
+                output_format: {
+                    type: 'string',
+                    enum: ['text', 'json'],
+                    default: 'text',
+                    description: 'text keeps the concise summary; json mirrors the stable structuredContent envelope',
+                },
+            },
+        },
+        outputSchema: {type: 'object', additionalProperties: true},
+    }))
 }
 
 // Import the tool modules (cache-busted when version > 0), build the catalog, apply the caps filter.
-// capsArg semantics: undefined/null = offline defaults (including explicit-call repo retargeting); a
+// capsArg semantics: undefined/null = offline defaults; a
 // present string (even '') is an explicit selection, so "select nothing" really exposes nothing.
 export async function loadHotApi(version, capsArg) {
     const v = version ? `?v=${version}` : ''
-    const [tg, ti, th, ta] = await Promise.all([
+    const [tg, ti, th, ta, tar, thi, tc] = await Promise.all([
         import(new URL(`./tools-graph.mjs${v}`, import.meta.url).href),
         import(new URL(`./tools-impact.mjs${v}`, import.meta.url).href),
         import(new URL(`./tools-health.mjs${v}`, import.meta.url).href),
         import(new URL(`./tools-actions.mjs${v}`, import.meta.url).href),
+        import(new URL(`./tools-architecture.mjs${v}`, import.meta.url).href),
+        import(new URL(`./tools-history.mjs${v}`, import.meta.url).href),
+        import(new URL(`./tools-company.mjs${v}`, import.meta.url).href),
     ])
-    const all = buildTools({tg, ti, th, ta})
-    const selected = capsArg == null ? DEFAULT_CAPS : String(capsArg).split(',').map((s) => s.trim()).filter(Boolean)
+    const all = buildTools({tg, ti, th, ta, tar, thi, tc})
+    const raw = capsArg == null ? 'offline' : String(capsArg).trim()
+    const selected = PROFILE_CAPS[raw] || raw.split(',').map((s) => s.trim()).filter(Boolean)
+        .flatMap((cap) => cap === 'online' ? ['advisories', 'hosted'] : [cap])
     const caps = new Set(selected)
     const tools = all.filter((t) => caps.has(t.cap))
     return {

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

@@ -0,0 +1,80 @@
+import {
+    CAPS, STATE, VERDICT, bounded, compareText, moduleId, nonNegativeInteger,
+} from './evidence-snapshot.common.mjs'
+
+function sanitizeModule(value) {
+    const id = moduleId(value?.name)
+    if (!id) return null
+    return {
+        id,
+        fileCount: nonNegativeInteger(value.fileCount),
+        nodeCount: nonNegativeInteger(value.nodeCount),
+        symbolCount: nonNegativeInteger(value.symbolCount),
+    }
+}
+
+function sanitizeModuleDependency(value) {
+    const from = moduleId(value?.from)
+    const to = moduleId(value?.to)
+    if (!from || !to || from === to) return null
+    return {from, to, count: nonNegativeInteger(value.count)}
+}
+
+function sortedModuleDependencies(values) {
+    return (Array.isArray(values) ? values : [])
+        .map(sanitizeModuleDependency)
+        .filter(Boolean)
+        .sort((a, b) => compareText(a.from, b.from) || compareText(a.to, b.to) || a.count - b.count)
+}
+
+export function buildArchitectureSection(graph, aggregate, audit, structure) {
+    if (!aggregate) {
+        return {
+            state: STATE.ERROR,
+            verdict: VERDICT.UNKNOWN,
+            completeness: {reasons: ['GRAPH_AGGREGATION_ERROR']},
+            modules: [],
+            dependencies: {runtime: [], typeOnly: [], compileOnly: []},
+            cycles: [],
+            boundaryViolations: [],
+        }
+    }
+
+    const modules = bounded(
+        (aggregate.modules || []).map(sanitizeModule).filter(Boolean).sort((a, b) => compareText(a.id, b.id)),
+        CAPS.modules,
+    )
+    const runtime = bounded(sortedModuleDependencies(aggregate.moduleEdges), CAPS.moduleDependencies)
+    const typeOnly = bounded(sortedModuleDependencies(aggregate.typeOnlyModuleEdges), CAPS.moduleDependencies)
+    const compileOnly = bounded(sortedModuleDependencies(aggregate.compileOnlyModuleEdges), CAPS.moduleDependencies)
+    const cycles = structure?.cycles || bounded([], CAPS.architectureFindings)
+    const boundaries = structure?.boundaries || bounded([], CAPS.architectureFindings)
+
+    const edgeTypesComplete = Number.isInteger(graph?.edgeTypesV) && graph.edgeTypesV >= 2
+    const auditComplete = audit?.ok === true
+    const structureComplete = structure?.state === STATE.COMPLETE
+    const state = edgeTypesComplete && auditComplete && structureComplete ? STATE.COMPLETE : STATE.PARTIAL
+    const fails = cycles.items.some((cycle) => cycle.kind === 'runtime') || boundaries.items.length > 0
+    return {
+        state,
+        verdict: fails ? VERDICT.FAIL : state === STATE.COMPLETE ? VERDICT.PASS : VERDICT.UNKNOWN,
+        completeness: {
+            modules: modules.completeness,
+            runtimeDependencies: runtime.completeness,
+            typeOnlyDependencies: typeOnly.completeness,
+            compileOnlyDependencies: compileOnly.completeness,
+            cycles: cycles.completeness,
+            boundaryViolations: boundaries.completeness,
+            reasons: [
+                ...(!edgeTypesComplete ? ['EDGE_TYPES_V2_REQUIRED'] : []),
+                ...(!auditComplete ? ['AUDIT_UNAVAILABLE'] : []),
+                ...(!structureComplete ? ['STRUCTURE_EVIDENCE_UNAVAILABLE'] : []),
+            ],
+        },
+        modules: modules.items,
+        dependencies: {runtime: runtime.items, typeOnly: typeOnly.items, compileOnly: compileOnly.items},
+        cycles: cycles.items,
+        boundaryViolations: boundaries.items,
+        boundaryRulesState: structure?.rulesState || STATE.ERROR,
+    }
+}

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

@@ -0,0 +1,160 @@
+import {createHash} from 'node:crypto'
+
+export const STATE = Object.freeze({
+    COMPLETE: 'COMPLETE',
+    PARTIAL: 'PARTIAL',
+    NOT_CHECKED: 'NOT_CHECKED',
+    NOT_APPLICABLE: 'NOT_APPLICABLE',
+    ERROR: 'ERROR',
+})
+
+export const VERDICT = Object.freeze({PASS: 'PASS', FAIL: 'FAIL', UNKNOWN: 'UNKNOWN'})
+
+export const CAPS = Object.freeze({
+    modules: 500,
+    moduleDependencies: 2_000,
+    architectureFindings: 150,
+    findings: 500,
+    hotspots: 250,
+    stackBadges: 100,
+    packages: 5_000,
+    directUsage: 1_000,
+    usageFiles: 20,
+    packageGraphNodes: 5_000,
+    packageGraphEdges: 20_000,
+    duplicateGroups: 100,
+    duplicateMembers: 12,
+    divergenceCandidates: 100,
+})
+
+export const COMPLEXITY_THRESHOLDS = Object.freeze({
+    loc: Object.freeze({warning: 120, high: 300}),
+    cyclomatic: Object.freeze({warning: 15, high: 30}),
+    params: Object.freeze({warning: 6, high: 10}),
+})
+
+const CONTROL_CHARS = /[\u0000-\u001f\u007f]/
+const ABSOLUTE_PATH_FRAGMENT = /(?:^|[\/\s"'`(=])[a-z]:[\\/]|(?:^|[\s"'`(=])(?:\\\\[^\\/\s]+(?:[\\/]|$)|file:(?:\/\/)?[\\/]|\/(?!\/)[^\s])/i
+const SAFE_TOKEN = /^[A-Za-z0-9@][A-Za-z0-9._:+/@-]*$/
+const SAFE_RULE = /^[a-z0-9][a-z0-9._-]*$/
+const SAFE_FINDING_ID = /^[a-f0-9]{8,64}$/i
+const SAFE_SEVERITY = new Set(['critical', 'high', 'medium', 'low', 'info'])
+const SAFE_CONFIDENCE = new Set(['high', 'medium', 'low'])
+const SAFE_CATEGORY = new Set(['unused', 'structure', 'vulnerability', 'malware'])
+const SAFE_CHECK_STATE = new Set(Object.values(STATE))
+
+export function metadataString(value, max = 512) {
+    return typeof value === 'string' && value.length > 0 && value.length <= max && !CONTROL_CHARS.test(value)
+        ? value
+        : undefined
+}
+
+export function privacySafeText(value, max = 512) {
+    const text = metadataString(value, max)
+    return text && !ABSOLUTE_PATH_FRAGMENT.test(text) ? text : undefined
+}
+
+export function safeToken(value, max = 256) {
+    const text = metadataString(value, max)
+    return text && SAFE_TOKEN.test(text) ? text : undefined
+}
+
+export function repoRelativePath(value, max = 4096) {
+    const raw = metadataString(value, max)
+    if (!raw) return undefined
+    const path = raw.replace(/\\/g, '/')
+    if (/^(?:[a-z][a-z0-9+.-]*:|\/)/i.test(path)) return undefined
+    const segments = path.split('/')
+    if (!segments.length || segments.some((segment) => !segment || segment === '.' || segment === '..')) return undefined
+    return path
+}
+
+export function graphId(value) {
+    const id = metadataString(value, 4096)
+    if (!id) return undefined
+    const hash = id.indexOf('#')
+    const file = hash < 0 ? id : id.slice(0, hash)
+    return repoRelativePath(file) ? id.replace(/\\/g, '/') : undefined
+}
+
+export function moduleId(value) {
+    if (value === '(root)') return '(root)'
+    return repoRelativePath(value)
+}
+
+export function nonNegativeInteger(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0
+        ? Math.trunc(value)
+        : 0
+}
+
+export function optionalNonNegativeInteger(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0
+        ? Math.trunc(value)
+        : undefined
+}
+
+export function addIf(out, key, value) {
+    if (value !== undefined) out[key] = value
+}
+
+export function compareText(a, b) {
+    return String(a).localeCompare(String(b), 'en')
+}
+
+export function bounded(sortedItems, cap) {
+    const items = sortedItems.slice(0, cap)
+    return {
+        items,
+        completeness: {
+            total: sortedItems.length,
+            returned: items.length,
+            truncated: sortedItems.length > items.length,
+        },
+    }
+}
+
+function stableStringify(value) {
+    if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`
+    if (value && typeof value === 'object') {
+        return `{${Object.keys(value).sort(compareText).map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(',')}}`
+    }
+    return JSON.stringify(value)
+}
+
+export function hashSnapshot(snapshot) {
+    return createHash('sha256').update(stableStringify(snapshot)).digest('hex')
+}
+
+export function normalizeCheckState(value) {
+    if (value === 'OK') return STATE.COMPLETE
+    return SAFE_CHECK_STATE.has(value) ? value : STATE.ERROR
+}
+
+export function sanitizeFinding(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return null
+    const id = metadataString(value.id, 64)
+    const category = metadataString(value.category, 32)
+    const rule = metadataString(value.rule, 64)
+    const severity = metadataString(value.severity, 16)
+    if (!id || !SAFE_FINDING_ID.test(id) || !category || !SAFE_CATEGORY.has(category) ||
+        !rule || !SAFE_RULE.test(rule) || !severity || !SAFE_SEVERITY.has(severity)) return null
+
+    const out = {id, category, rule, severity}
+    const confidence = metadataString(value.confidence, 16)
+    if (confidence && SAFE_CONFIDENCE.has(confidence)) out.confidence = confidence
+    addIf(out, 'file', repoRelativePath(value.file))
+    const line = optionalNonNegativeInteger(value.line)
+    if (line !== undefined) out.line = line
+    addIf(out, 'symbol', privacySafeText(value.symbol, 256))
+    addIf(out, 'package', safeToken(value.package))
+    addIf(out, 'version', safeToken(value.version, 128))
+    addIf(out, 'graphNodeId', graphId(value.graphNodeId))
+    return out
+}
+
+export function numericRecord(value, keys) {
+    const out = {}
+    for (const key of keys) out[key] = nonNegativeInteger(value?.[key])
+    return out
+}