weavatrix 0.1.3 → 0.2.0

package/src/mcp/sync-payload.mjs

@@ -1,7 +1,14 @@
 // Versioned, explicit wire schema for sync_graph. Never forward graph.json wholesale: it is a local
 // cache file and may contain future fields or attacker-injected data that are not safe to upload.
+import {sanitizeEvidenceSnapshot} from './sync-evidence.mjs';
 
 const CONTROL_CHARS = /[\u0000-\u001f\u007f]/;
+const ABSOLUTE_PATH_FRAGMENT = /(?:^|[\/\s"'`(=])[a-z]:[\\/]|(?:^|[\s"'`(=])(?:\\\\[^\\/\s]+(?:[\\/]|$)|file:(?:\/\/)?[\\/]|\/(?!\/)[^\s])/i;
+
+export const MAX_SYNC_BODY_BYTES = 8 * 1024 * 1024;
+export const MAX_SYNC_NODES = 25_000;
+export const MAX_SYNC_LINKS = 100_000;
+export const MAX_SYNC_EXTERNAL_IMPORTS = 50_000;
 
 function metadataString(value, max = 4096) {
     return typeof value === 'string' && value.length > 0 && value.length <= max && !CONTROL_CHARS.test(value)
@@ -9,6 +16,72 @@ function metadataString(value, max = 4096) {
         : undefined;
 }
 
+// graph.json is derived data and may be edited independently of the repository. Never trust a path
+// merely because it occupies an allowlisted field: sync only accepts canonical-looking repo-relative
+// paths, on every host OS. Graph IDs append `#symbol@line`, so validate their file portion separately
+// while preserving the complete ID on the wire.
+function repoRelativePathString(value, max = 4096) {
+    const path = metadataString(value, max);
+    if (!path) return undefined;
+    if (/^(?:[a-z][a-z0-9+.-]*:|[\\/])/i.test(path)) return undefined; // URI, drive path, POSIX or UNC absolute
+    const segments = path.split(/[\\/]/);
+    if (segments.some((segment) => segment === '.' || segment === '..')) return undefined;
+    return path;
+}
+
+function graphIdString(value) {
+    const id = metadataString(value);
+    if (!id) return undefined;
+    const hash = id.indexOf('#');
+    const file = hash < 0 ? id : id.slice(0, hash);
+    return repoRelativePathString(file) ? id : undefined;
+}
+
+// Optional display metadata is still attacker-controlled graph data. Keep useful labels/import
+// specifiers, but never let an absolute host path hide inside one of those free-text fields.
+function privacySafeText(value, max = 4096) {
+    const text = metadataString(value, max);
+    if (!text) return undefined;
+    return ABSOLUTE_PATH_FRAGMENT.test(text) ? undefined : text;
+}
+
+function repoPathV3(value, max = 4096) {
+    const path = repoRelativePathString(value, max);
+    return path ? path.replace(/\\/g, '/') : undefined;
+}
+
+function graphIdV3(value) {
+    const id = metadataString(value);
+    if (!id) return undefined;
+    const hash = id.indexOf('#');
+    const file = hash < 0 ? id : id.slice(0, hash);
+    const safeFile = repoPathV3(file);
+    if (!safeFile) return undefined;
+    if (hash < 0) return safeFile;
+    const suffix = id.slice(hash);
+    // Builder IDs are `#symbol@line` (optionally with a short collision suffix). A symbol suffix
+    // never needs a path separator or whitespace; rejecting both closes an otherwise opaque channel.
+    if (suffix.length > 512 || !/^#[^\\/\s\u0000-\u001f\u007f]{1,511}$/u.test(suffix)) return undefined;
+    return `${safeFile}${suffix}`;
+}
+
+function safeToken(value, max = 256) {
+    const token = metadataString(value, max);
+    if (!token || !/^[\p{L}\p{N}_.:@+\-#$<>()\[\],]+$/u.test(token)) return undefined;
+    return token;
+}
+
+function packageName(value) {
+    const name = metadataString(value, 256);
+    return name && /^(?:@[a-z0-9._-]+\/)?[a-z0-9][a-z0-9._-]*$/i.test(name) ? name : undefined;
+}
+
+function externalSpecifier(value) {
+    const spec = metadataString(value, 512);
+    if (!spec || ABSOLUTE_PATH_FRAGMENT.test(spec) || /^(?:[a-z]:[\\/]|[\\/]|\.\.?[\\/])/i.test(spec)) return undefined;
+    return /^[a-z0-9@][a-z0-9@._:/+\-]*$/i.test(spec) ? spec : undefined;
+}
+
 function finiteNumber(value) {
     return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
 }
@@ -37,12 +110,12 @@ function sanitizeComplexity(value) {
 
 function sanitizeNode(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
-    const id = metadataString(value.id);
+    const id = graphIdString(value.id);
     if (!id) return null;
     const out = {id};
     setIf(out, 'label', metadataString(value.label, 1024));
     setIf(out, 'file_type', metadataString(value.file_type, 32));
-    setIf(out, 'source_file', metadataString(value.source_file));
+    setIf(out, 'source_file', repoRelativePathString(value.source_file));
     const sourceLocation = metadataString(value.source_location, 32);
     const sourceEnd = metadataString(value.source_end, 32);
     if (sourceLocation && /^L\d+$/.test(sourceLocation)) out.source_location = sourceLocation;
@@ -57,13 +130,14 @@ function sanitizeNode(value) {
 
 function sanitizeLink(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
-    const source = metadataString(value.source);
-    const target = metadataString(value.target);
+    const source = graphIdString(value.source);
+    const target = graphIdString(value.target);
     if (!source || !target) return null;
     const out = {source, target};
     setIf(out, 'relation', metadataString(value.relation, 32));
     setIf(out, 'confidence', metadataString(value.confidence, 32));
     if (value.typeOnly === true) out.typeOnly = true;
+    if (value.compileOnly === true) out.compileOnly = true;
     const line = finiteNumber(value.line);
     if (line !== undefined && Number.isInteger(line) && line >= 0) out.line = line;
     setIf(out, 'specifier', metadataString(value.specifier));
@@ -72,7 +146,7 @@ function sanitizeLink(value) {
 
 function sanitizeExternalImport(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
-    const file = metadataString(value.file);
+    const file = repoRelativePathString(value.file);
     if (!file) return null;
     const out = {file};
     for (const key of ['spec', 'target']) setIf(out, key, metadataString(value[key]));
@@ -85,12 +159,90 @@ function sanitizeExternalImport(value) {
     return out;
 }
 
+function sanitizeNodeV3(value) {
+    const out = sanitizeNode(value);
+    if (!out) return null;
+    const id = graphIdV3(value.id);
+    if (!id) return null;
+    const sourceFile = value.source_file == null ? undefined : repoPathV3(value.source_file);
+    if (value.source_file != null && !sourceFile) return null;
+    const hash = id.indexOf('#');
+    const idFile = hash < 0 ? id : id.slice(0, hash);
+    if (sourceFile && idFile !== sourceFile) return null;
+    out.id = id;
+    const label = privacySafeText(value.label, 1024);
+    if (label) out.label = label;
+    else delete out.label;
+    const fileType = safeToken(value.file_type, 32);
+    if (fileType) out.file_type = fileType;
+    else delete out.file_type;
+    if (sourceFile) out.source_file = sourceFile;
+    else delete out.source_file;
+    for (const key of ['symbol_kind', 'member_of', 'visibility']) setIf(out, key, safeToken(value[key], 128));
+    if (out.complexity) {
+        for (const key of ['family', 'scope', 'complexityScope', 'confidence']) {
+            const safe = safeToken(value.complexity?.[key], 32);
+            if (safe) out.complexity[key] = safe;
+            else delete out.complexity[key];
+        }
+    }
+    return out;
+}
+
+function sanitizeLinkV3(value) {
+    const out = sanitizeLink(value);
+    if (!out) return null;
+    const source = graphIdV3(value.source);
+    const target = graphIdV3(value.target);
+    if (!source || !target) return null;
+    out.source = source;
+    out.target = target;
+    for (const key of ['relation', 'confidence']) {
+        const safe = safeToken(value[key], 32);
+        if (safe) out[key] = safe;
+        else delete out[key];
+    }
+    const specifier = privacySafeText(value.specifier, 1024);
+    if (specifier) out.specifier = specifier;
+    else delete out.specifier;
+    return out;
+}
+
+function sanitizeExternalImportV3(value) {
+    const out = sanitizeExternalImport(value);
+    if (!out) return null;
+    const file = repoPathV3(value.file);
+    if (!file) return null;
+    out.file = file;
+    setIf(out, 'spec', externalSpecifier(value.spec));
+    if (!externalSpecifier(value.spec)) delete out.spec;
+    setIf(out, 'pkg', packageName(value.pkg));
+    if (!packageName(value.pkg)) delete out.pkg;
+    for (const key of ['kind', 'ecosystem']) {
+        const safe = safeToken(value[key], 64);
+        if (safe) out[key] = safe;
+        else delete out[key];
+    }
+    if (value.target != null) {
+        const target = repoPathV3(value.target);
+        if (target) out.target = target;
+        else delete out.target;
+    }
+    if (value.typeOnly === true) out.typeOnly = true;
+    return out;
+}
+
+function assertArrayLimit(raw, key, limit) {
+    const count = Array.isArray(raw[key]) ? raw[key].length : 0;
+    if (count > limit) throw new Error(`${key} has ${count} entries; maximum is ${limit}`);
+}
+
 export function createSyncPayload(raw) {
     if (!raw || typeof raw !== 'object' || Array.isArray(raw) || raw.repoBoundaryV !== 1) {
         throw new Error('graph predates repository-boundary hardening');
     }
-    if (!Number.isInteger(raw.edgeTypesV) || raw.edgeTypesV < 1) {
-        throw new Error('graph predates typed import edges');
+    if (!Number.isInteger(raw.edgeTypesV) || raw.edgeTypesV < 2) {
+        throw new Error('graph predates compile-only edge metadata');
     }
     const nodes = Array.isArray(raw.nodes) ? raw.nodes.map(sanitizeNode).filter(Boolean) : [];
     const links = Array.isArray(raw.links) ? raw.links.map(sanitizeLink).filter(Boolean) : [];
@@ -100,7 +252,7 @@ export function createSyncPayload(raw) {
     return {
         syncPayloadV: 2,
         repoBoundaryV: 1,
-        edgeTypesV: 1,
+        edgeTypesV: 2,
         extImportsV: Number.isInteger(raw.extImportsV) ? raw.extImportsV : 0,
         complexityV: Number.isInteger(raw.complexityV) ? raw.complexityV : 0,
         nodes,
@@ -108,3 +260,37 @@ export function createSyncPayload(raw) {
         externalImports,
     };
 }
+
+export function createSyncPayloadV3(raw, evidence) {
+    // Reuse the v2 schema gates, but construct v3 arrays independently so the stricter path/identity
+    // rules cannot change graph-only compatibility for existing endpoints.
+    const base = createSyncPayload(raw);
+    assertArrayLimit(raw, 'nodes', MAX_SYNC_NODES);
+    assertArrayLimit(raw, 'links', MAX_SYNC_LINKS);
+    assertArrayLimit(raw, 'externalImports', MAX_SYNC_EXTERNAL_IMPORTS);
+    const nodes = (raw.nodes || []).map(sanitizeNodeV3).filter(Boolean);
+    const nodeIds = new Set();
+    for (const node of nodes) {
+        if (nodeIds.has(node.id)) throw new Error(`duplicate node id in graph: ${node.id}`);
+        nodeIds.add(node.id);
+    }
+    const links = (raw.links || []).map(sanitizeLinkV3).filter(Boolean);
+    for (const link of links) {
+        if (!nodeIds.has(link.source) || !nodeIds.has(link.target)) {
+            throw new Error(`dangling link in graph: ${link.source} -> ${link.target}`);
+        }
+    }
+    const externalImports = (raw.externalImports || []).map(sanitizeExternalImportV3).filter(Boolean);
+    return {
+        syncPayloadV: 3,
+        repoBoundaryV: base.repoBoundaryV,
+        edgeTypesV: base.edgeTypesV,
+        extImportsV: base.extImportsV,
+        complexityV: base.complexityV,
+        evidenceV: 1,
+        nodes,
+        links,
+        externalImports,
+        evidence: sanitizeEvidenceSnapshot(evidence),
+    };
+}

package/src/mcp/tool-result.mjs

@@ -0,0 +1,51 @@
+// MCP tool results keep a concise human summary and a stable machine-readable envelope together.
+// Older clients continue to consume TextContent; MCP 2025-06 clients can use structuredContent
+// directly without scraping prose. Tool implementations may opt into richer `result` data through
+// toolResult(), while legacy string-returning tools still receive a deterministic envelope.
+
+export const TOOL_RESULT_SCHEMA = 'weavatrix.tool.v1'
+
+export function toolResult(text, result, extra = {}) {
+    return {
+        __weavatrixToolResult: true,
+        text: String(text ?? ''),
+        result: result && typeof result === 'object' ? result : {},
+        warnings: Array.isArray(extra.warnings) ? extra.warnings : [],
+        page: extra.page && typeof extra.page === 'object' ? extra.page : undefined,
+        completeness: extra.completeness && typeof extra.completeness === 'object' ? extra.completeness : undefined,
+    }
+}
+
+function repoName(repoRoot) {
+    const parts = String(repoRoot || '').replace(/[\\/]+$/, '').split(/[\\/]/)
+    const name = parts.pop() || 'unknown'
+    return name.normalize('NFKC').replace(/[^a-z0-9._-]+/gi, '-').replace(/^-+|-+$/g, '').slice(0, 128) || 'unknown'
+}
+
+export function normalizeToolResult({toolName, value, args, ctx, refresh, warnings = [], freshness = 'unknown'}) {
+    const rich = value && typeof value === 'object' && value.__weavatrixToolResult === true
+    const text = rich ? value.text : String(value ?? '')
+    const resultWarnings = [...(rich ? value.warnings : []), ...warnings]
+    if (refresh?.notice) resultWarnings.unshift({code: 'GRAPH_AUTO_REFRESHED', message: refresh.notice})
+    if (refresh?.error) resultWarnings.unshift({code: 'GRAPH_AUTO_REFRESH_FAILED', message: refresh.error})
+    const structured = {
+        schemaVersion: TOOL_RESULT_SCHEMA,
+        tool: String(toolName || ''),
+        repo: {name: repoName(ctx?.repoRoot)},
+        graph: {
+            revision: refresh?.revision || null,
+            freshness: refresh?.error ? 'stale' : (refresh?.kind ? 'fresh' : freshness),
+            update: refresh?.kind || 'none',
+            changedFiles: Number(refresh?.changedFiles) || 0,
+        },
+        result: rich ? value.result : {text},
+        evidence: [],
+        warnings: resultWarnings,
+        page: rich ? (value.page || {}) : {},
+        ...(rich && value.completeness ? {completeness: value.completeness} : {}),
+    }
+    return {
+        text: args?.output_format === 'json' ? JSON.stringify(structured, null, 2) : `Repository: ${structured.repo.name}\n${text}`,
+        structured,
+    }
+}

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')
 }
@@ -45,7 +72,7 @@ export async function tOpenRepo(g, args, ctx) {
     if (existsSync(graphPath)) {
         try {
             const saved = JSON.parse(readFileSync(graphPath, 'utf8'))
-            upgrade = !Number.isInteger(saved.edgeTypesV) || saved.edgeTypesV < 1
+            upgrade = !Number.isInteger(saved.edgeTypesV) || saved.edgeTypesV < 2
         } catch {
             upgrade = true
         }
@@ -53,7 +80,7 @@ export async function tOpenRepo(g, args, ctx) {
     if (!existsSync(graphPath) || upgrade) {
         if (args.build === false) {
             return upgrade
-                ? `The existing graph for ${repoPath} predates typed import edges. Re-call without build:false to upgrade it before switching.`
+                ? `The existing graph for ${repoPath} predates compile-only edge metadata (edge schema v2). Re-call without build:false to upgrade it before switching.`
                 : `No graph yet for ${repoPath} (expected at ${graphPath}). Re-call without build:false to build one — large repos can take minutes.`
         }
         const mode = ['no-tests', 'tests-only', 'full'].includes(args.mode) ? args.mode : 'full'
@@ -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'}).`
     }
-    const buildNote = built ? (upgrade ? ' (graph upgraded to typed import edges)' : ' (graph built fresh)') : ''
+    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.`
     }