weavatrix 0.1.4 → 0.2.0

package/src/mcp/tools-actions.mjs

@@ -1,29 +1,56 @@
 // Action tools: rebuild the graph, the explicit 'retarget' group, and the explicit 'online' group
 // (the ONLY tools that ever touch the network).
 // Hot-reloadable (re-imported by catalog.mjs on change).
-import {readFileSync, writeFileSync, existsSync, readdirSync, statSync, realpathSync} from 'node:fs'
-import {join, dirname, isAbsolute} from 'node:path'
-import {prevGraphPathFor, diffGraphs, formatGraphDiff} from './graph-context.mjs'
+import {readFileSync, writeFileSync, existsSync, statSync, realpathSync} from 'node:fs'
+import {dirname, join, isAbsolute} from 'node:path'
+import {prevGraphPathFor, diffGraphs, formatGraphDiff, graphStaleness} from './graph-context.mjs'
 import {buildGraphForRepo} from '../build-graph.js'
-import {graphOutDirForRepo} from '../graph/layout.js'
+import {graphHomeDir, graphOutDirForModule, graphOutDirForRepo} from '../graph/layout.js'
+import {liveRepositoryRecords, registerRepository, repositoryRecord} from '../graph/repo-registry.js'
 import {refreshAdvisories, storeMeta, DEFAULT_STORE} from '../security/advisory-store.js'
 import {collectInstalled} from '../security/installed.js'
-import {createSyncPayload} from './sync-payload.mjs'
+import {createSyncPayload, createSyncPayloadV3, MAX_SYNC_BODY_BYTES} from './sync-payload.mjs'
+import {createEvidenceSnapshot} from './evidence-snapshot.mjs'
+import {writeCachedArchitectureContract} from '../analysis/architecture-contract.js'
+
+const MAX_SYNC_GRAPH_FILE_BYTES = 64 * 1024 * 1024
+
+function syncRepoLabel(repoRoot) {
+    const basename = String(repoRoot || '').replace(/[\\/]+$/, '').split(/[\\/]/).pop() || 'repo'
+    const safe = basename.normalize('NFKC').replace(/[^a-z0-9._-]+/gi, '-').replace(/^-+|-+$/g, '')
+    return (safe || 'repo').slice(0, 128)
+}
 
 export async function tRebuildGraph(g, args, ctx) {
     if (!ctx.repoRoot) return 'Rebuild needs the repo root (not provided to this server).'
     const mode = ['no-tests', 'tests-only', 'full'].includes(args.mode) ? args.mode : 'full'
+    const scope = String(args.scope || '').replace(/\\/g, '/').replace(/^\/+|\/+$/g, '')
+    if (scope) {
+        const scopedDir = graphOutDirForModule(ctx.repoRoot, scope)
+        const scoped = await buildGraphForRepo(ctx.repoRoot, {mode, scope, outDir: scopedDir})
+        if (!scoped || !scoped.ok) return `Scoped graph build failed: ${(scoped && scoped.error) || 'unknown error'}`
+        return [
+            `Built an isolated scoped graph for ${scope} (${mode}). ${scoped.log || ''}.`,
+            `The active full-repository graph was not replaced, so this operation cannot report a false full→scope structural delta.`,
+            `Scoped graph: ${join(scopedDir, 'graph.json')}`,
+        ].join('\n')
+    }
     // snapshot the outgoing state: bytes → graph.prev.json (for graph_diff later), struct → inline delta
     let prevBytes = null
     try { prevBytes = readFileSync(ctx.graphPath) } catch { /* first build — nothing to diff against */ }
-    const before = g?.nodes ? {nodes: g.nodes, links: g.links, edgeTypesV: g.edgeTypesV || 0} : null
-    const res = await buildGraphForRepo(ctx.repoRoot, {mode, scope: args.scope || ''})
+    const before = g?.nodes ? {
+        nodes: g.nodes, links: g.links,
+        edgeTypesV: g.edgeTypesV || 0,
+        barrelResolutionV: g.barrelResolutionV || 0,
+        extractorSchemaV: g.extractorSchemaV || 0,
+    } : null
+    const res = await buildGraphForRepo(ctx.repoRoot, {mode, scope: '', outDir: ctx.graphPath ? dirname(ctx.graphPath) : undefined})
     if (!res || !res.ok) return `Graph rebuild failed: ${(res && res.error) || 'unknown error'}`
     if (prevBytes) { try { writeFileSync(prevGraphPathFor(ctx.graphPath), prevBytes) } catch { /* snapshot is best-effort */ } }
     const fresh = ctx.reload() // refresh THIS server's in-memory graph so subsequent tool calls see the new graph
     const delta = before && fresh ? formatGraphDiff(diffGraphs(before, fresh)) : null
     return [
-        `Rebuilt the graph (${mode}${args.scope ? `, scope=${args.scope}` : ''}). ${res.log || ''}. In-memory graph reloaded — graph tools now reflect it.`,
+        `Rebuilt the graph (${mode}). ${res.log || ''}. In-memory graph reloaded — graph tools now reflect it.`,
         delta
     ].filter(Boolean).join('\n\n')
 }
@@ -71,31 +98,23 @@ export async function tOpenRepo(g, args, ctx) {
         ctx.reload()
         return `Failed to load ${graphPath} — still targeting the previous repo (${prev.repoRoot || 'none'}).`
     }
+    registerRepository({repoPath, graphDir: graphOutDirForRepo(repoPath), graphHome: graphHomeDir()})
     const buildNote = built ? (upgrade ? ' (graph upgraded to edge metadata v2)' : ' (graph built fresh)') : ''
     return `Opened ${repoPath}${buildNote}: ${loaded.nodes.length} nodes / ${loaded.links.length} edges. All tools now target this repo.`
 }
 
 // Sibling repos that already have a built graph in the central weavatrix-graphs folder — open_repo candidates.
 export function tListKnownRepos(g, args, ctx) {
-    if (!ctx.repoRoot) return 'No repo root — cannot locate the central graphs folder.'
-    const parent = dirname(ctx.repoRoot)
-    const root = join(parent, 'weavatrix-graphs')
+    const root = graphHomeDir()
     const norm = (p) => String(p).replace(/[\\/]+/g, '/').toLowerCase()
-    let entries = []
-    try { entries = readdirSync(root, {withFileTypes: true}) } catch { return `No central graphs folder at ${root}.` }
-    const rows = []
-    for (const entry of entries) {
-        if (!entry.isDirectory()) continue
-        const graphPath = join(root, entry.name, 'graph.json')
-        try {
-            const st = statSync(graphPath)
-            rows.push({name: entry.name, repoPath: join(parent, entry.name), builtAt: st.mtime.toISOString()})
-        } catch { /* no graph built for this entry */ }
-    }
-    if (!rows.length) return `No built graphs under ${root}.`
+    const rows = liveRepositoryRecords(root).map((record) => ({
+        ...record,
+        builtAt: statSync(join(record.graphDir, 'graph.json')).mtime.toISOString(),
+    }))
+    if (!rows.length) return `No registered graphs under ${root}. Build a repository once with open_repo or rebuild_graph.`
     return [
-        `Repos with built graphs under ${root} (switch with open_repo):`,
-        ...rows.map((r) => `  ${norm(r.repoPath) === norm(ctx.repoRoot) ? '»' : ' '} ${r.name} — graph built ${r.builtAt}  (${r.repoPath})`),
+        `Known repositories (${rows.length}) in ${root}:`,
+        ...rows.map((r) => `  ${norm(r.repoPath) === norm(ctx.repoRoot) ? '»' : ' '} ${r.label} [${r.repositoryId}] — graph built ${r.builtAt}  (${r.repoPath})`),
     ].join('\n')
 }
 
@@ -120,6 +139,32 @@ export async function tRefreshAdvisories(g, args, ctx) {
     ].filter(Boolean).join('\n')
 }
 
+export async function tPullArchitectureContract(g, args, ctx) {
+    if (!ctx.repoRoot || !ctx.graphPath) return 'No active repository graph — open_repo first.'
+    const syncUrl = process.env.WEAVATRIX_SYNC_URL
+    const token = process.env.WEAVATRIX_SYNC_TOKEN
+    if (!syncUrl || !token) return 'Hosted architecture pull is not configured. Use the hosted profile with WEAVATRIX_SYNC_URL and WEAVATRIX_SYNC_TOKEN, or keep .weavatrix/architecture.json locally.'
+    let url
+    try { url = process.env.WEAVATRIX_ARCHITECTURE_URL || new URL('/api/v1/architecture-contract', syncUrl).toString() }
+    catch { return 'WEAVATRIX_SYNC_URL is invalid.' }
+    const registry = repositoryRecord(ctx.repoRoot, graphHomeDir())
+        || registerRepository({repoPath: ctx.repoRoot, graphDir: graphOutDirForRepo(ctx.repoRoot), graphHome: graphHomeDir()})
+    const timeoutMs = Math.min(120000, Math.max(1000, Number(args.timeout_ms) || 30000))
+    try {
+        const res = await fetch(url, {
+            headers: {authorization: `Bearer ${token}`, 'x-weavatrix-repository-id': registry.repositoryId},
+            signal: AbortSignal.timeout(timeoutMs),
+        })
+        const body = await res.json().catch(() => null)
+        if (!res.ok) return `Hosted architecture endpoint answered HTTP ${res.status}; the local contract cache was not changed.`
+        if (body?.state === 'NOT_CONFIGURED' || !body?.contract) return 'Hosted target architecture is NOT_CONFIGURED. Define and save it in the Architecture editor first.'
+        const stored = writeCachedArchitectureContract(ctx.graphPath, body.contract)
+        return `Pulled target architecture ${stored.contract.name} (${stored.contract.style}, ${stored.contract.enforcement}) into the local graph cache. get_architecture_contract and verify_architecture now use it.`
+    } catch (error) {
+        return `Hosted architecture pull failed: ${error.message}; the previous local contract, if any, remains active.`
+    }
+}
+
 // Push the current graph.json to a user-configured endpoint. Off until WEAVATRIX_SYNC_URL is set.
 // The payload is graph metadata (paths, symbols/ranges, imports, edges, metrics), never file contents.
 export async function tSyncGraph(g, args, ctx) {
@@ -130,13 +175,38 @@ export async function tSyncGraph(g, args, ctx) {
     }
     if (!g) return 'No graph loaded — build one first (open_repo / rebuild_graph).'
     let raw
-    try { raw = JSON.parse(readFileSync(ctx.graphPath, 'utf8')) } catch (e) { return `Cannot read ${ctx.graphPath}: ${e.message}` }
+    try {
+        const size = statSync(ctx.graphPath).size
+        if (size > MAX_SYNC_GRAPH_FILE_BYTES) {
+            return `Cannot sync: graph.json is ${Math.ceil(size / 1024 / 1024)} MB; the local safety limit is ${MAX_SYNC_GRAPH_FILE_BYTES / 1024 / 1024} MB.`
+        }
+        raw = JSON.parse(readFileSync(ctx.graphPath, 'utf8'))
+    } catch (e) { return `Cannot read ${ctx.graphPath}: ${e.message}` }
+    const requestedVersion = Number(args.payload_version) === 2 ? 2 : 3
     let payload
-    try { payload = createSyncPayload(raw) } catch (e) {
+    try {
+        if (requestedVersion === 2) {
+            payload = createSyncPayload(raw)
+        } else {
+            if (!ctx.repoRoot) return 'Cannot build evidence: no repository root is active.'
+            if (graphStaleness(ctx).stale) {
+                return 'Cannot sync evidence from a stale graph. Run rebuild_graph, then call sync_graph again.'
+            }
+            const evidence = await createEvidenceSnapshot({repoRoot: ctx.repoRoot, graph: raw})
+            payload = createSyncPayloadV3(raw, evidence)
+        }
+    } catch (e) {
         return `Cannot sync: ${e.message}. Run rebuild_graph once before sync_graph.`
     }
     const body = JSON.stringify(payload)
-    const repoName = String(ctx.repoRoot || '').replace(/[\\/]+$/, '').split(/[\\/]/).pop() || 'repo'
+    const bodyBytes = Buffer.byteLength(body)
+    if (bodyBytes > MAX_SYNC_BODY_BYTES) {
+        return `Cannot sync: payload is ${Math.ceil(bodyBytes / 1024)} KB; the hosted safety limit is ${MAX_SYNC_BODY_BYTES / 1024} KB. Narrow the graph scope and rebuild before retrying.`
+    }
+    const repoName = syncRepoLabel(ctx.repoRoot)
+    const registry = repositoryRecord(ctx.repoRoot, graphHomeDir())
+        || registerRepository({repoPath: ctx.repoRoot, graphDir: graphOutDirForRepo(ctx.repoRoot), graphHome: graphHomeDir()})
+    const timeoutMs = Math.min(120000, Math.max(1000, Number(args.timeout_ms) || 30000))
     try {
         const res = await fetch(url, {
             method: 'POST',
@@ -144,12 +214,23 @@ export async function tSyncGraph(g, args, ctx) {
                 'content-type': 'application/json',
                 'x-weavatrix-payload-version': String(payload.syncPayloadV),
                 'x-weavatrix-repo': repoName,
+                'x-weavatrix-repository-id': registry.repositoryId,
                 ...(process.env.WEAVATRIX_SYNC_TOKEN ? {authorization: `Bearer ${process.env.WEAVATRIX_SYNC_TOKEN}`} : {}),
             },
             body,
+            signal: AbortSignal.timeout(timeoutMs),
         })
-        if (!res.ok) return `Sync endpoint answered HTTP ${res.status} — graph NOT accepted.`
-        return `Graph for ${repoName} (${payload.nodes.length} nodes / ${payload.links.length} edges, ${Math.round(Buffer.byteLength(body) / 1024)} KB) pushed to ${url}.`
+        if (!res.ok) {
+            const accepted = res.headers?.get?.('x-weavatrix-accept-payload-versions')
+            const compatibility = (res.status === 415 || res.status === 422) && accepted
+                ? ` Endpoint accepts payload version(s) ${accepted}; retry with payload_version:2 only if you intentionally want graph-only sync.`
+                : ''
+            return `Sync endpoint answered HTTP ${res.status} — graph NOT accepted.${compatibility}`
+        }
+        const evidenceNote = payload.syncPayloadV === 3
+            ? ` + evidence ${payload.evidence?.snapshotHash?.slice(0, 12) || 'unknown'}`
+            : ''
+        return `Graph for ${repoName} (${payload.nodes.length} nodes / ${payload.links.length} edges${evidenceNote}, ${Math.round(bodyBytes / 1024)} KB) pushed to ${url}.`
     } catch (e) {
         return `Sync failed: ${e.message} — the graph stays local.`
     }

package/src/mcp/tools-architecture.mjs

@@ -0,0 +1,144 @@
+// Executable target architecture for agents: read the active contract before a change, then run the
+// same deterministic verifier after it. No tool silently edits policy or accepts debt.
+import {contractForChange, loadArchitectureContract, normalizeArchitectureContract, verifyArchitecture} from '../analysis/architecture-contract.js'
+import {detectRepoStack} from '../scan/discover.js'
+import {toolResult} from './tool-result.mjs'
+
+const stackIds = (repoRoot) => {
+    try {
+        const stack = detectRepoStack(repoRoot)
+        return ['languages', 'runtimes', 'tests', 'infra', 'deploy']
+            .flatMap((category) => (Array.isArray(stack?.[category]) ? stack[category] : []))
+            .map((item) => String(item?.id || '')).filter(Boolean)
+    } catch { return [] }
+}
+
+function activeContract(ctx) {
+    if (!ctx?.repoRoot) return {contract: null, source: null, error: 'no repository root is active'}
+    return loadArchitectureContract(ctx.repoRoot, ctx.graphPath)
+}
+
+function starterContract(g) {
+    const files = [...new Set((g?.nodes || [])
+        .filter((node) => !String(node.id).includes('#'))
+        .map((node) => String(node.source_file || node.id || '').replace(/\\/g, '/'))
+        .filter(Boolean))]
+    const groups = new Map()
+    for (const file of files) {
+        const parts = file.split('/').filter(Boolean)
+        const depth = ['src', 'app', 'lib', 'packages', 'services'].includes(parts[0]) ? 2 : 1
+        const path = parts.slice(0, Math.max(1, Math.min(depth, parts.length - 1))).join('/') || '(root)'
+        groups.set(path, (groups.get(path) || 0) + 1)
+    }
+    const components = [...groups].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, 80)
+        .filter(([path]) => path !== '(root)')
+        .map(([path], index) => ({
+            id: path.toLowerCase().replace(/[^a-z0-9._:-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 100) || `component-${index + 1}`,
+            name: path,
+            paths: [path],
+        }))
+    return normalizeArchitectureContract({
+        name: 'Proposed no-regressions baseline', style: 'custom', enforcement: 'ratchet', components,
+        dependencyRules: [],
+        budgets: {runtimeCycles: 0, maxFileLoc: 300, maxFunctionLoc: 120, maxCyclomatic: 15, maxModuleFiles: 80, minModuleCohesion: .5, maxModuleBoundaryRatio: .65},
+        technologies: {required: [], forbidden: []}, exceptions: [], ratchet: {baseline: {fingerprints: [], metrics: {}}},
+    })
+}
+
+function notConfiguredResult(g, action) {
+    const starter = starterContract(g)
+    return toolResult([
+        `Architecture ${action} is NOT_CONFIGURED — no target contract is active.`,
+        `A source-free starter was inferred from ${starter.components.length} path territories; review it before saving because folders are evidence, not semantic truth.`,
+        'Next: save it as .weavatrix/architecture.json (offline) or approve it in the hosted Architecture editor, then call verify_architecture.',
+    ].join('\n'), {
+        state: 'NOT_CONFIGURED',
+        remediation: {
+            offlinePath: '.weavatrix/architecture.json',
+            hostedAction: 'Open Architecture → choose intended style → Save target & baseline',
+            nextTool: 'verify_architecture',
+        },
+        starterContract: starter,
+    })
+}
+
+export function tGetArchitectureContract(g, args, ctx) {
+    const loaded = activeContract(ctx)
+    if (!loaded.contract) {
+        const text = loaded.error
+            ? `Architecture contract is invalid (${loaded.source || 'unknown'}): ${loaded.error}`
+            : 'No target architecture contract is active.'
+        if (!loaded.error) return notConfiguredResult(g, 'lookup')
+        return toolResult(text, {state: 'ERROR', source: loaded.source, error: loaded.error})
+    }
+    const contract = loaded.contract
+    return toolResult([
+        `Target architecture: ${contract.name} (${contract.style}, ${contract.enforcement}).`,
+        `Contract ${contract.contractHash.slice(0, 12)} from ${loaded.source}; ${contract.components.length} components, ${contract.dependencyRules.length} dependency rules.`,
+        `Quality budgets: ${Object.entries(contract.budgets).map(([key, value]) => `${key}=${value}`).join(', ') || '(none)'}.`,
+    ].join('\n'), {state: 'ACTIVE', source: loaded.source, contract})
+}
+
+export function tPrepareChange(g, args, ctx) {
+    const loaded = activeContract(ctx)
+    if (!loaded.contract) return notConfiguredResult(g, 'preflight')
+    const prepared = contractForChange(loaded.contract, args.files)
+    const intent = String(args.intent || '').slice(0, 500)
+    return toolResult([
+        `Architecture preflight for ${prepared.files.length} file(s)${intent ? ` — ${intent}` : ''}.`,
+        `Affected target components: ${prepared.components.join(', ') || '(unmapped)'}.`,
+        `Applicable rules: ${prepared.rules.map((rule) => rule.id).join(', ') || '(none)'}.`,
+        'Run verify_architecture after the edit; do not silently add an exception or rewrite the target contract.',
+    ].join('\n'), {state: 'READY', intent, contractHash: loaded.contract.contractHash, ...prepared})
+}
+
+export function tVerifyArchitecture(g, args, ctx) {
+    const loaded = activeContract(ctx)
+    if (!loaded.contract) return notConfiguredResult(g, 'verification')
+    const verification = verifyArchitecture({graph: g, contract: loaded.contract, technologies: stackIds(ctx.repoRoot)})
+    const groups = [['new', verification.new], ['existing', verification.existing], ['fixed', verification.fixed], ['excepted', verification.excepted]]
+    const lines = [
+        `Architecture verify: ${verification.status} (${verification.enforcement}; contract ${verification.contractHash.slice(0, 12)}).`,
+        `New ${verification.new.length} · existing debt ${verification.existing.length} · fixed ${verification.fixed.length} · excepted ${verification.excepted.length}.`,
+        ...groups.filter(([, values]) => values.length).flatMap(([label, values]) => [
+            `${label}:`,
+            ...values.slice(0, 20).map((item) => typeof item === 'string' ? `  ${item}` : `  ${item.ruleId}: ${item.evidence}${item.current != null ? ` (${item.current} > ${item.target})` : ''}`),
+        ]),
+    ]
+    return toolResult(lines.join('\n'), {state: verification.status, source: loaded.source, verification}, {
+        completeness: {violationsReturned: Math.min(20, verification.new.length + verification.existing.length), violationsTotal: verification.new.length + verification.existing.length},
+    })
+}
+
+export function tExplainArchitectureViolation(g, args, ctx) {
+    const loaded = activeContract(ctx)
+    if (!loaded.contract) return toolResult('No active architecture contract.', {state: 'NOT_CONFIGURED'})
+    const verification = verifyArchitecture({graph: g, contract: loaded.contract, technologies: stackIds(ctx.repoRoot)})
+    const fingerprint = String(args.fingerprint || '')
+    const item = [...verification.new, ...verification.existing, ...verification.excepted]
+        .find((entry) => entry.fingerprint === fingerprint)
+    if (!item) return toolResult(`Violation ${fingerprint || '(missing)'} is not active in the current verification.`, {state: 'NOT_FOUND', fingerprint})
+    const rule = loaded.contract.dependencyRules.find((candidate) => candidate.id === item.ruleId)
+    return toolResult([
+        `${item.ruleId}: ${item.evidence}.`,
+        rule?.reason ? `Reason: ${rule.reason}` : 'The finding violates an explicit dependency or quality rule in the active target contract.',
+        'Preferred action: change the dependency/metric. If that is intentionally impossible, propose a time-bounded exception for human review.',
+    ].join('\n'), {state: 'ACTIVE', violation: item, rule: rule || null})
+}
+
+export function tProposeArchitectureException(g, args, ctx) {
+    const loaded = activeContract(ctx)
+    if (!loaded.contract) return toolResult('No active architecture contract.', {state: 'NOT_CONFIGURED'})
+    const verification = verifyArchitecture({graph: g, contract: loaded.contract, technologies: stackIds(ctx.repoRoot)})
+    const item = [...verification.new, ...verification.existing].find((entry) => entry.fingerprint === String(args.fingerprint || ''))
+    if (!item) return toolResult('Only an active violation can be proposed as an exception.', {state: 'NOT_FOUND'})
+    const proposal = {
+        fingerprint: item.fingerprint,
+        reason: String(args.reason || '').trim().slice(0, 300),
+        ...(args.expires ? {expires: String(args.expires)} : {}),
+    }
+    const checked = normalizeArchitectureContract({...loaded.contract, exceptions: [...loaded.contract.exceptions, proposal]})
+    const normalized = checked.exceptions.find((entry) => entry.fingerprint === item.fingerprint)
+    if (!normalized || !normalized.reason) return toolResult('A non-empty reason and optional YYYY-MM-DD expiry are required.', {state: 'INVALID'})
+    return toolResult('Exception proposal prepared for human review; the contract was not changed.', {state: 'PROPOSED', proposal: normalized, contractHash: loaded.contract.contractHash})
+}

package/src/mcp/tools-company.mjs

@@ -0,0 +1,273 @@
+// Cross-repository HTTP contract intelligence. Repository paths are resolved only through the
+// local global registry; callers can select an opaque repository UUID or an unambiguous label but
+// can never pass an arbitrary filesystem path through this tool.
+import {join} from 'node:path'
+import {analyzeHttpContracts} from '../analysis/http-contracts.js'
+import {buildGraphForRepo} from '../build-graph.js'
+import {graphHomeDir} from '../graph/layout.js'
+import {liveRepositoryRecords} from '../graph/repo-registry.js'
+import {loadGraph} from './graph-context.mjs'
+import {toolResult} from './tool-result.mjs'
+
+const selectorText = (value) => String(value ?? '').trim()
+
+function selectRecord(records, selector) {
+    const query = selectorText(selector)
+    if (!query) return {error: 'repository selector is required'}
+    const byId = records.find((record) => record.repositoryId === query)
+    if (byId) return {record: byId}
+    const byLabel = records.filter((record) => String(record.label || '').toLowerCase() === query.toLowerCase())
+    if (byLabel.length === 1) return {record: byLabel[0]}
+    if (byLabel.length > 1) return {
+        error: `repository label "${query}" is ambiguous; use one of these repository IDs`,
+        candidates: byLabel.map((record) => ({repositoryId: record.repositoryId, label: record.label})),
+    }
+    return {error: `repository "${query}" is not present in the live global graph registry`}
+}
+
+function safeAlias(record, records) {
+    const base = String(record.label || 'repo').normalize('NFKC')
+        .replace(/[^a-z0-9._-]+/gi, '-').replace(/^-+|-+$/g, '').slice(0, 56) || 'repo'
+    const duplicates = records.filter((item) => String(item.label || '').toLowerCase() === String(record.label || '').toLowerCase())
+    return duplicates.length > 1 ? `${base}-${String(record.repositoryId).slice(0, 8)}` : base
+}
+
+function publicRecord(record, alias) {
+    return {repositoryId: record.repositoryId, label: record.label, alias}
+}
+
+function safeRefreshReason(record, error) {
+    let message = String(error instanceof Error ? error.message : error || 'graph refresh failed')
+    for (const path of [record.repoPath, record.graphDir]) {
+        if (!path) continue
+        message = message.split(String(path)).join(record.label || 'repository')
+        message = message.split(String(path).replace(/\\/g, '/')).join(record.label || 'repository')
+    }
+    return message.replace(/[\r\n]+/g, ' ').trim().slice(0, 400) || 'graph refresh failed'
+}
+
+async function reconcileGraph(record, alias, role, graphHome) {
+    let build
+    try {
+        build = await buildGraphForRepo(record.repoPath, {
+            mode: 'full',
+            scope: '',
+            outDir: record.graphDir,
+            graphHome,
+        })
+    } catch (error) {
+        build = {ok: false, error: safeRefreshReason(record, error)}
+    }
+    const refreshKind = build?.refresh?.kind || null
+    const changedFiles = Array.isArray(build?.refresh?.changedFiles) ? build.refresh.changedFiles : []
+    const publicStatus = {
+        role,
+        repository: publicRecord(record, alias),
+        status: build?.ok ? (refreshKind === 'none' ? 'CURRENT' : 'REFRESHED') : 'STALE_FALLBACK',
+        refresh: build?.ok ? {
+            kind: refreshKind || 'full',
+            reason: String(build?.refresh?.reason || 'graph-rebuilt'),
+            changedFileCount: changedFiles.length,
+        } : null,
+    }
+    if (build?.ok) {
+        try {
+            return {record, alias, graph: loadGraph(join(record.graphDir, 'graph.json')), publicStatus}
+        } catch (error) {
+            const reason = `refreshed graph could not be loaded: ${safeRefreshReason(record, error)}`
+            return {record, alias, graph: null, reason, publicStatus: {...publicStatus, status: 'FAILED', reason}}
+        }
+    }
+
+    const reason = `graph refresh failed: ${safeRefreshReason(record, build?.error)}`
+    try {
+        return {
+            record,
+            alias,
+            graph: loadGraph(join(record.graphDir, 'graph.json')),
+            reason: `${reason}; stale registered graph used`,
+            publicStatus: {...publicStatus, reason: `${reason}; stale registered graph used`},
+        }
+    } catch (error) {
+        const loadReason = `${reason}; registered graph could not be loaded: ${safeRefreshReason(record, error)}`
+        return {record, alias, graph: null, reason: loadReason, publicStatus: {...publicStatus, status: 'FAILED', reason: loadReason}}
+    }
+}
+
+function verdictFor(analysis) {
+    const endpointsWithCallers = analysis.endpoints.filter((endpoint) => endpoint.callsites.length > 0)
+    const affectedFiles = new Set()
+    const affectedScreens = new Set()
+    for (const endpoint of endpointsWithCallers) {
+        for (const item of endpoint.affected.files || []) affectedFiles.add(`${item.client}\0${item.file}`)
+        for (const item of endpoint.affected.screens || []) affectedScreens.add(`${item.client}\0${item.file}`)
+    }
+    let code = 'NO_ENDPOINTS_MATCHED', risk = 'unknown'
+    if (analysis.totals.endpoints > 0 && analysis.totals.matches === 0) {
+        code = analysis.totals.methodMismatches > 0 ? 'HTTP_METHOD_MISMATCH' : 'NO_STATIC_CLIENT_CALLERS'
+        risk = analysis.totals.methodMismatches > 0 ? 'high' : 'unknown'
+    } else if (analysis.totals.matches > 0 && analysis.totals.methodMismatches > 0) {
+        code = 'CLIENTS_AT_RISK_WITH_METHOD_MISMATCHES'; risk = 'high'
+    } else if (analysis.totals.matches > 0) {
+        code = 'CLIENTS_AT_RISK'; risk = 'medium'
+    }
+    return {
+        code,
+        risk,
+        endpointsWithCallers: endpointsWithCallers.length,
+        callsites: analysis.totals.matches,
+        affectedFiles: affectedFiles.size,
+        affectedScreens: affectedScreens.size,
+        methodMismatches: analysis.totals.methodMismatches,
+        uncertainCalls: analysis.totals.uncertainCalls,
+    }
+}
+
+function verdictLine(verdict, endpoints) {
+    if (verdict.code === 'NO_ENDPOINTS_MATCHED') {
+        return 'VERDICT NO_ENDPOINTS_MATCHED — no backend endpoint satisfied the requested method/path/change filter.'
+    }
+    if (verdict.code === 'NO_STATIC_CLIENT_CALLERS') {
+        return `VERDICT NO_STATIC_CLIENT_CALLERS — ${endpoints} backend endpoint(s) matched, but no bounded literal/template client call was proven; this is unknown, not proof of no consumers.`
+    }
+    if (verdict.code === 'HTTP_METHOD_MISMATCH') {
+        return `VERDICT HTTP_METHOD_MISMATCH — ${verdict.methodMismatches} client call(s) match the route shape with a different method.`
+    }
+    return `VERDICT ${verdict.code} — ${verdict.callsites} callsite(s) reach ${verdict.endpointsWithCallers} endpoint(s); ${verdict.affectedScreens} screen(s) and ${verdict.affectedFiles} file(s) are in the bounded blast radius.`
+}
+
+export async function tTraceApiContract(_g, args = {}, ctx = {}) {
+    const graphHome = ctx.graphHome || graphHomeDir()
+    const records = liveRepositoryRecords(graphHome)
+    if (!records.length) return toolResult(
+        'VERDICT NOT_CONFIGURED — the global repository registry has no live graphs. Open/build both the backend and client repositories first.',
+        {status: 'NOT_CONFIGURED', availableRepositories: []},
+    )
+
+    const backendSelection = selectRecord(records, args.backend)
+    if (!backendSelection.record) return toolResult(
+        `VERDICT INVALID_REPOSITORY — ${backendSelection.error}.`,
+        {status: 'INVALID_REPOSITORY', role: 'backend', ...backendSelection, availableRepositories: records.map((record) => publicRecord(record, safeAlias(record, records)))},
+    )
+    const rawClients = Array.isArray(args.clients) ? args.clients.slice(0, 20) : []
+    if (!rawClients.length) return toolResult(
+        'VERDICT INVALID_REPOSITORY — at least one client repository ID or label is required.',
+        {status: 'INVALID_REPOSITORY', role: 'clients'},
+    )
+    const clientRecords = []
+    for (const selector of rawClients) {
+        const selected = selectRecord(records, selector)
+        if (!selected.record) return toolResult(
+            `VERDICT INVALID_REPOSITORY — ${selected.error}.`,
+            {status: 'INVALID_REPOSITORY', role: 'client', selector, ...selected},
+        )
+        if (!clientRecords.some((record) => record.repositoryId === selected.record.repositoryId)) clientRecords.push(selected.record)
+    }
+    if (clientRecords.some((record) => record.repositoryId === backendSelection.record.repositoryId)) return toolResult(
+        'VERDICT INVALID_REPOSITORY — backend and client selections must be distinct repositories.',
+        {status: 'INVALID_REPOSITORY', role: 'clients'},
+    )
+
+    const backend = backendSelection.record
+    const backendAlias = safeAlias(backend, records)
+    const clients = clientRecords.map((record) => ({record, alias: safeAlias(record, records)}))
+    const reconciled = []
+    for (const selected of [
+        {record: backend, alias: backendAlias, role: 'backend'},
+        ...clients.map(({record, alias}) => ({record, alias, role: 'client'})),
+    ]) {
+        reconciled.push(await reconcileGraph(selected.record, selected.alias, selected.role, graphHome))
+    }
+    const backendGraph = reconciled[0]
+    const clientGraphs = reconciled.slice(1)
+    const reconciliationReasons = reconciled.filter((item) => item.reason).map((item) => item.reason)
+    const graphReconciliation = reconciled.map((item) => item.publicStatus)
+    if (!backendGraph.graph || clientGraphs.some((item) => !item.graph)) {
+        const reasons = reconciliationReasons.length ? reconciliationReasons : ['one or more selected graphs could not be refreshed and loaded']
+        const completeness = {complete: false, status: 'PARTIAL', reasons}
+        return toolResult(
+            `VERDICT PARTIAL — selected repository graphs could not all be refreshed and loaded.\nCompleteness: partial — ${reasons.join('; ')}.`,
+            {
+                crossRepoHttpContractV: 1,
+                status: 'PARTIAL',
+                repositories: {
+                    backend: publicRecord(backend, backendAlias),
+                    clients: clients.map(({record, alias}) => publicRecord(record, alias)),
+                },
+                graphReconciliation,
+                completeness,
+            },
+            {completeness, warnings: [{code: 'CROSS_REPO_GRAPH_REFRESH_PARTIAL', message: reasons.join('; ')}]},
+        )
+    }
+
+    try {
+        const analysis = analyzeHttpContracts({
+            backend: {id: backendAlias, repoRoot: backend.repoPath, graph: backendGraph.graph},
+            clients: clientGraphs.map((item) => ({id: item.alias, repoRoot: item.record.repoPath, graph: item.graph})),
+            method: args.method,
+            path: args.path,
+            changedFiles: args.changed_files,
+            includeTests: args.include_tests === true,
+            maxImpactDepth: args.max_impact_depth,
+            maxEndpoints: args.max_endpoints,
+            maxMatches: args.max_matches,
+            maxAffectedFiles: args.max_affected_files,
+        })
+        const verdict = verdictFor(analysis)
+        const reasons = [...new Set([...reconciliationReasons, ...(analysis.completeness?.reasons || [])])]
+        const completeness = {
+            complete: reasons.length === 0 && analysis.completeness?.complete === true,
+            status: reasons.length === 0 && analysis.completeness?.complete === true ? 'COMPLETE' : 'PARTIAL',
+            reasons,
+        }
+        const topN = Math.max(1, Math.min(50, Number(args.top_n) || 10))
+        const ranked = [...analysis.endpoints].sort((left, right) =>
+            right.callsites.length - left.callsites.length ||
+            right.affected.files.length - left.affected.files.length ||
+            left.path.localeCompare(right.path))
+        const lines = [
+            verdictLine(verdict, analysis.totals.endpoints),
+            `Scope: ${backend.label} → ${clients.map(({record}) => record.label).join(', ')}; ${analysis.totals.endpoints} endpoint(s), ${analysis.totals.clientCalls} inspected client call(s), ${analysis.totals.uncertainCalls} uncertain.`,
+            ...ranked.slice(0, topN).flatMap((endpoint) => {
+                const location = endpoint.file ? ` (${endpoint.backend}:${endpoint.file}${endpoint.line ? `:${endpoint.line}` : ''})` : ''
+                const callsites = endpoint.callsites.slice(0, 3)
+                    .map((call) => `    caller ${call.clientRepo}:${call.file}:${call.line} (${call.match.confidence}, ${call.match.kind})`)
+                const screens = endpoint.affected.screens.slice(0, 3)
+                    .map((screen) => `    screen ${screen.client}:${screen.file} (distance ${screen.distance})`)
+                return [
+                    `  ${endpoint.method} ${endpoint.path}${location} → ${endpoint.callsites.length} callsite(s), ${endpoint.affected.screens.length} screen(s), ${endpoint.affected.files.length} affected file(s)`,
+                    ...callsites,
+                    ...screens,
+                ]
+            }),
+            completeness.complete
+                ? 'Completeness: complete within the declared repository graphs and static HTTP-call model.'
+                : `Completeness: partial — ${completeness.reasons.join('; ')}.`,
+        ]
+        const result = {
+            crossRepoHttpContractV: 1,
+            verdict,
+            repositories: {
+                backend: publicRecord(backend, backendAlias),
+                clients: clients.map(({record, alias}) => publicRecord(record, alias)),
+            },
+            ...analysis,
+            status: completeness.status,
+            graphReconciliation,
+            completeness,
+        }
+        return toolResult(lines.join('\n'), result, {
+            completeness,
+            warnings: completeness.complete ? [] : [{code: 'CROSS_REPO_ANALYSIS_PARTIAL', message: completeness.reasons.join('; ')}],
+        })
+    } catch (error) {
+        const reason = error instanceof Error ? error.message : 'cross-repository analysis failed'
+        const completeness = {complete: false, status: 'PARTIAL', reasons: [reason]}
+        return toolResult(
+            `VERDICT PARTIAL — ${reason}.`,
+            {status: 'PARTIAL', graphReconciliation, completeness},
+            {completeness, warnings: [{code: 'CROSS_REPO_ANALYSIS_PARTIAL', message: reason}]},
+        )
+    }
+}