weavatrix 0.2.12 → 0.2.14

package/src/mcp/actions/graph-sync.mjs

@@ -0,0 +1,195 @@
+import {createHash} from 'node:crypto'
+import {readFileSync, statSync} from 'node:fs'
+import {graphStaleness} from '../graph-context.mjs'
+import {graphHomeDir, graphOutDirForRepo} from '../../graph/layout.js'
+import {registerRepository, repositoryRecord} from '../../graph/repo-registry.js'
+import {createSyncPayload, createSyncPayloadV3, MAX_SYNC_BODY_BYTES} from '../sync-payload.mjs'
+import {createEvidenceSnapshot} from '../evidence-snapshot.mjs'
+import {toolResult} from '../tool-result.mjs'
+
+const MAX_SYNC_GRAPH_FILE_BYTES = 64 * 1024 * 1024
+const SYNC_PREVIEW_TTL_MS = 5 * 60 * 1000
+const MAX_SYNC_PREVIEWS = 4
+const syncPreviews = new Map()
+
+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 function syncDestination(raw) {
+    let url
+    try { url = new URL(raw) } catch { throw new Error('WEAVATRIX_SYNC_URL is invalid') }
+    if (!['http:', 'https:'].includes(url.protocol)) throw new Error('WEAVATRIX_SYNC_URL must use HTTPS (or HTTP for loopback development)')
+    if (url.username || url.password) throw new Error('WEAVATRIX_SYNC_URL must not contain embedded credentials; use WEAVATRIX_SYNC_TOKEN')
+    if (url.hash) throw new Error('WEAVATRIX_SYNC_URL must not contain a fragment')
+    const loopback = ['localhost', '127.0.0.1', '[::1]', '::1'].includes(url.hostname.toLowerCase())
+    if (url.protocol !== 'https:' && !loopback) throw new Error('WEAVATRIX_SYNC_URL must use HTTPS unless the destination is loopback')
+    const display = `${url.origin}${url.pathname}${url.search ? ' (query redacted)' : ''}`
+    return {url: url.toString(), display}
+}
+
+function pruneSyncPreviews(now = Date.now()) {
+    for (const [token, preview] of syncPreviews) if (preview.expiresAt <= now) syncPreviews.delete(token)
+    while (syncPreviews.size >= MAX_SYNC_PREVIEWS) syncPreviews.delete(syncPreviews.keys().next().value)
+}
+
+function confirmationToken({url, repositoryId, payloadVersion, bodyHash}) {
+    return createHash('sha256')
+        .update(`weavatrix-sync-preview-v1\0${url}\0${repositoryId}\0${payloadVersion}\0${bodyHash}`)
+        .digest('hex').slice(0, 24)
+}
+
+function syncSectionSummary(payload) {
+    if (payload.syncPayloadV !== 3) return 'graph topology only (explicit V2 compatibility mode)'
+    const sections = payload.evidence?.sections || {}
+    const names = Object.entries(sections).map(([name, section]) => `${name}:${section?.state || section?.verdict || 'included'}`)
+    return names.join(', ') || 'bounded architecture/health/stack/package/duplicate evidence'
+}
+
+function syncPreviewText(preview, {expired = false} = {}) {
+    return [
+        `SYNC PREVIEW${expired ? ' (the supplied confirmation was missing, expired, or did not match)' : ''} — no network request was made.`,
+        `Destination: ${preview.destinationDisplay}.`,
+        `Repository: ${preview.repoName}; opaque repository UUID: ${preview.repositoryId}.`,
+        `Payload V${preview.payload.syncPayloadV}: ${preview.payload.nodes.length} nodes / ${preview.payload.links.length} edges, ${Math.round(preview.bodyBytes / 1024)} KB; body SHA-256 ${preview.bodyHash.slice(0, 12)}.`,
+        `Payload fields: ${Object.keys(preview.payload).sort().join(', ')}.`,
+        `Included sections: ${syncSectionSummary(preview.payload)}.`,
+        'Excluded by the wire allowlist: source bodies, snippets, absolute host paths, environment values, credentials, Git remotes, and unknown fields.',
+        `After the user approves this exact destination and summary, call sync_graph again within 5 minutes with dry_run:false and confirm_token: "${preview.token}".`,
+    ].join('\n')
+}
+
+async function sendSyncPreview(preview, timeoutMs) {
+    try {
+        const res = await fetch(preview.url, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                'x-weavatrix-payload-version': String(preview.payload.syncPayloadV),
+                'x-weavatrix-repo': preview.repoName,
+                'x-weavatrix-repository-id': preview.repositoryId,
+                ...(process.env.WEAVATRIX_SYNC_TOKEN ? {authorization: `Bearer ${process.env.WEAVATRIX_SYNC_TOKEN}`} : {}),
+            },
+            body: preview.body,
+            signal: AbortSignal.timeout(timeoutMs),
+        })
+        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}; create and approve a new V2 preview only if graph-only sync is intentional.`
+                : ''
+            return `Sync endpoint ${preview.destinationDisplay} answered HTTP ${res.status} — graph NOT accepted.${compatibility}`
+        }
+        syncPreviews.delete(preview.token)
+        const evidenceNote = preview.payload.syncPayloadV === 3
+            ? ` + evidence ${preview.payload.evidence?.snapshotHash?.slice(0, 12) || 'unknown'}`
+            : ''
+        return `Graph for ${preview.repoName} (${preview.payload.nodes.length} nodes / ${preview.payload.links.length} edges${evidenceNote}, ${Math.round(preview.bodyBytes / 1024)} KB) pushed to approved destination ${preview.destinationDisplay}.`
+    } catch (error) {
+        return `Sync failed: ${error.message} — the graph stays local; the approved preview remains retryable until it expires.`
+    }
+}
+
+async function buildSyncPreview(g, args, ctx) {
+    const configuredUrl = process.env.WEAVATRIX_SYNC_URL
+    if (!configuredUrl) {
+        return 'Graph sync is not configured (optional feature). Set WEAVATRIX_SYNC_URL to the upload endpoint'
+            + ' (and WEAVATRIX_SYNC_TOKEN for bearer auth) in the MCP registration env, then call again.'
+    }
+    let destination
+    try { destination = syncDestination(configuredUrl) }
+    catch (error) { return `Graph sync is not configured safely: ${error.message}.` }
+    if (!g) return 'No graph loaded — build one first (open_repo / rebuild_graph).'
+    let raw
+    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 {
+        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 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 bodyHash = createHash('sha256').update(body).digest('hex')
+    const token = confirmationToken({url: destination.url, repositoryId: registry.repositoryId, payloadVersion: payload.syncPayloadV, bodyHash})
+    const preview = {
+        token, url: destination.url, destinationDisplay: destination.display,
+        graphPath: ctx.graphPath, repoName, repositoryId: registry.repositoryId,
+        payload, body, bodyBytes, bodyHash, expiresAt: Date.now() + SYNC_PREVIEW_TTL_MS,
+    }
+    syncPreviews.set(token, preview)
+    return preview
+}
+
+function previewResult(preview, {expired = false} = {}) {
+    if (typeof preview === 'string') return preview
+    return toolResult(syncPreviewText(preview, {expired}), {
+        status: 'PREVIEW_READY', networkRequestMade: false,
+        destination: preview.destinationDisplay, repository: preview.repoName,
+        repositoryId: preview.repositoryId, payloadVersion: preview.payload.syncPayloadV,
+        nodes: preview.payload.nodes.length, links: preview.payload.links.length,
+        bodyBytes: preview.bodyBytes, bodyHash: preview.bodyHash,
+        payloadFields: Object.keys(preview.payload).sort(), sections: syncSectionSummary(preview.payload),
+        expiresAt: new Date(preview.expiresAt).toISOString(), confirmToken: preview.token,
+    }, {completeness: {status: 'COMPLETE', reason: 'exact allowlisted payload serialized locally; no network request made'}})
+}
+
+// Build the exact upload body and approval token without any network request. Kept separate from the
+// mutating tool so safety layers and humans can approve a local preview without authorizing egress.
+export async function tPreviewSyncGraph(g, args, ctx) {
+    pruneSyncPreviews()
+    return previewResult(await buildSyncPreview(g, args, ctx))
+}
+
+// Push the exact payload previously approved through preview_sync. The old dry_run form remains a
+// compatibility alias for one release, but can never send unless dry_run:false and the token matches.
+export async function tSyncGraph(g, args, ctx) {
+    if (args.dry_run !== false) {
+        pruneSyncPreviews()
+        const preview = await buildSyncPreview(g, args, ctx)
+        if (typeof preview === 'string') return preview
+        const suppliedToken = String(args.confirm_token || '').trim()
+        const exact = suppliedToken && suppliedToken === preview.token
+        return `${syncPreviewText(preview, {expired: !!suppliedToken && !exact})}${exact ? '\nConfirmation token recognized, but dry_run is still true; no network request was made.' : ''}`
+    }
+    const configuredUrl = process.env.WEAVATRIX_SYNC_URL
+    if (!configuredUrl) return 'Graph sync is not configured (optional feature). Set WEAVATRIX_SYNC_URL first.'
+    let destination
+    try { destination = syncDestination(configuredUrl) }
+    catch (error) { return `Graph sync is not configured safely: ${error.message}.` }
+    pruneSyncPreviews()
+    const suppliedToken = String(args.confirm_token || '').trim()
+    const approved = suppliedToken ? syncPreviews.get(suppliedToken) : null
+    if (approved && approved.expiresAt > Date.now()
+        && approved.url === destination.url && approved.graphPath === ctx.graphPath) {
+        const timeoutMs = Math.min(120000, Math.max(1000, Number(args.timeout_ms) || 30000))
+        return sendSyncPreview(approved, timeoutMs)
+    }
+    const preview = await buildSyncPreview(g, args, ctx)
+    return typeof preview === 'string' ? preview : syncPreviewText(preview, {expired: true})
+}
+

package/src/mcp/actions/hosted-architecture.mjs

@@ -0,0 +1,57 @@
+import {writeCachedArchitectureContract} from '../../analysis/architecture-contract.js'
+import {graphHomeDir, graphOutDirForRepo} from '../../graph/layout.js'
+import {registerRepository, repositoryRecord} from '../../graph/repo-registry.js'
+import {toolResult} from '../tool-result.mjs'
+const syncVersion = new URL(import.meta.url).search
+const {syncDestination} = await import(new URL(`./graph-sync.mjs${syncVersion}`, import.meta.url).href)
+
+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 {
+        const configured = process.env.WEAVATRIX_ARCHITECTURE_URL || new URL('/api/v1/architecture-contract', syncUrl).toString()
+        url = syncDestination(configured).url
+    } catch (error) { return `Hosted architecture pull is not configured safely: ${error.message}.` }
+    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) {
+            const serverCode = String(body?.error?.code || body?.state || '').toUpperCase()
+            const state = res.status === 401 ? 'AUTH_REQUIRED'
+                : res.status === 403 ? 'FORBIDDEN'
+                    : res.status === 404 && ['REPOSITORY_NOT_FOUND', 'NOT_FOUND'].includes(serverCode) ? 'REPOSITORY_NOT_REGISTERED'
+                        : res.status === 404 ? 'ENDPOINT_NOT_FOUND'
+                        : res.status === 409 ? 'REPOSITORY_NOT_READY'
+                            : 'HTTP_ERROR'
+            const next = state === 'REPOSITORY_NOT_REGISTERED'
+                ? 'The Hosted endpoint is reachable, but this UUID has not completed a preview-confirmed repository sync.'
+                : state === 'ENDPOINT_NOT_FOUND'
+                    ? 'The configured architecture endpoint does not exist; verify WEAVATRIX_ARCHITECTURE_URL or the URL derived from WEAVATRIX_SYNC_URL.'
+                : res.status === 401 || res.status === 403
+                    ? 'Check the hosted token and repository access; no local cache entry was changed.'
+                    : res.status === 409
+                        ? 'Sync/register this repository first, then create or pull its target contract.'
+                        : 'Check the hosted service status and configured endpoint before retrying.'
+            return toolResult(`Hosted architecture pull: ${state} (HTTP ${res.status}). ${next} The previous local contract cache remains unchanged.`, {
+                state, httpStatus: res.status, serverCode: serverCode || null, cacheChanged: false,
+            })
+        }
+        if (body?.state === 'NOT_CONFIGURED' || !body?.contract) return toolResult(
+            'Hosted target architecture is NOT_CONFIGURED. Repository sync and authentication succeeded; define and save a target in the Architecture editor first.',
+            {state: 'NOT_CONFIGURED', repositoryId: registry.repositoryId, cacheChanged: false},
+        )
+        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.`
+    }
+}

package/src/mcp/architecture-bootstrap.mjs

@@ -0,0 +1,168 @@
+// Explicit two-step local architecture bootstrap. Preview is pure; approval writes only the exact
+// previewed contract with a short-lived one-time token and never overwrites an active policy.
+import {createHash, randomBytes} from 'node:crypto'
+import {existsSync, mkdirSync, writeFileSync} from 'node:fs'
+import {join} from 'node:path'
+import {
+    loadArchitectureContract, normalizeArchitectureContract, verifyArchitecture,
+} from '../analysis/architecture-contract.js'
+import {createRepoBoundary} from '../repo-path.js'
+import {detectRepoStack} from '../scan/discover.js'
+import {toolResult} from './tool-result.mjs'
+
+const version = new URL(import.meta.url).search
+const starter = await import(new URL(`./architecture-starter.mjs${version}`, import.meta.url).href)
+const {createArchitectureStarter, proposeObservedDependencyDirections} = starter
+
+const PREVIEW_TTL_MS = 5 * 60_000
+const previews = new Map()
+
+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 [] }
+}
+const sha256 = (value) => createHash('sha256').update(value).digest('hex')
+
+function currentFingerprints(verification) {
+    return [...verification.new, ...verification.existing]
+        .map((item) => item.fingerprint).sort((a, b) => a.localeCompare(b))
+}
+
+function baselineMetrics(verification) {
+    return Object.fromEntries(['runtimeCycles', 'violations', 'componentDependencies', 'mappedComponents']
+        .map((key) => [key, verification.metrics?.[key]])
+        .filter(([, value]) => Number.isFinite(value)))
+}
+
+function materializeCandidate(candidate, verification, baselineMode) {
+    if (baselineMode !== 'accept-current') return normalizeArchitectureContract(candidate)
+    return normalizeArchitectureContract({
+        ...candidate,
+        ratchet: {baseline: {
+            fingerprints: currentFingerprints(verification),
+            metrics: baselineMetrics(verification),
+        }},
+    })
+}
+
+function activeContract(ctx) {
+    if (!ctx?.repoRoot) return {contract: null, source: null, error: 'no repository root is active'}
+    return loadArchitectureContract(ctx.repoRoot, ctx.graphPath)
+}
+
+function preview(g, args, ctx) {
+    const active = activeContract(ctx)
+    if (active.contract) return toolResult(
+        `Architecture bootstrap refused: an active contract already exists at ${active.source}.`,
+        {state: 'ALREADY_CONFIGURED', source: active.source, contractHash: active.contract.contractHash},
+    )
+    if (active.error) return toolResult(
+        `Architecture bootstrap refused: ${active.source || 'contract'} is invalid (${active.error}).`,
+        {state: 'ERROR', source: active.source, error: active.error},
+    )
+    const baselineMode = args?.baseline_mode === 'accept-current' ? 'accept-current' : 'none'
+    let candidate, starterProposal = null
+    try {
+        starterProposal = args?.candidate_contract ? null : createArchitectureStarter(g, ctx?.repoRoot)
+        candidate = args?.candidate_contract
+            ? normalizeArchitectureContract(args.candidate_contract)
+            : starterProposal.contract
+    } catch (error) {
+        return toolResult(`Candidate architecture contract is invalid: ${error.message}`, {state: 'INVALID', error: error.message})
+    }
+    const technologies = stackIds(ctx?.repoRoot)
+    const candidateVerification = verifyArchitecture({graph: g, contract: candidate, technologies})
+    const materializedContract = materializeCandidate(candidate, candidateVerification, baselineMode)
+    const materializedVerification = verifyArchitecture({graph: g, contract: materializedContract, technologies})
+    const contents = `${JSON.stringify(materializedContract, null, 2)}\n`
+    const contentHash = sha256(contents)
+    const token = randomBytes(12).toString('hex')
+    const expiresAt = new Date(Date.now() + PREVIEW_TTL_MS).toISOString()
+    previews.set(token, {
+        repoRoot: String(ctx?.repoRoot || ''), graphPath: String(ctx?.graphPath || ''),
+        contract: materializedContract, contents, contentHash,
+        verificationHash: materializedVerification.verificationHash,
+        expiresAt: Date.parse(expiresAt),
+    })
+    return toolResult([
+        `Architecture bootstrap PREVIEW only; no file was written. Candidate verification: ${candidateVerification.status}.`,
+        baselineMode === 'accept-current'
+            ? `Explicit accept-current baseline would record ${currentFingerprints(candidateVerification).length} current finding fingerprint(s).`
+            : 'No current findings were added to the baseline.',
+        `Review the materialized contract and then approve with confirm_token "${token}" before ${expiresAt}.`,
+    ].join('\n'), {
+        state: 'PREVIEW', wrote: false, baselineMode,
+        candidateVerification, materializedVerification, materializedContract,
+        observedDependencyProposals: proposeObservedDependencyDirections(g, materializedContract.components),
+        budgetProposals: starterProposal?.budgetProposals || [],
+        starterMethodology: starterProposal?.methodology,
+        patch: {operation: 'create', path: '.weavatrix/architecture.json', contentHash, contents},
+        confirmToken: token, expiresAt,
+    })
+}
+
+function approve(g, args, ctx) {
+    const token = String(args?.confirm_token || '')
+    const pending = previews.get(token)
+    if (!pending) return toolResult(
+        'Architecture approval refused: run a fresh preview and provide its exact confirm_token.',
+        {state: 'CONFIRMATION_REQUIRED', wrote: false},
+    )
+    previews.delete(token)
+    if (pending.expiresAt < Date.now()) return toolResult(
+        'Architecture approval refused: the preview expired; run preview again.',
+        {state: 'PREVIEW_EXPIRED', wrote: false},
+    )
+    if (pending.repoRoot !== String(ctx?.repoRoot || '') || pending.graphPath !== String(ctx?.graphPath || '')) {
+        return toolResult('Architecture approval refused: the active repository changed after preview.', {
+            state: 'REPOSITORY_CHANGED', wrote: false,
+        })
+    }
+    const active = activeContract(ctx)
+    if (active.contract || active.error) return toolResult(
+        `Architecture approval refused: ${active.source || 'a contract'} appeared or changed after preview.`,
+        {state: active.error ? 'ERROR' : 'ALREADY_CONFIGURED', wrote: false, source: active.source, error: active.error || undefined},
+    )
+    const verification = verifyArchitecture({
+        graph: g, contract: pending.contract, technologies: stackIds(ctx?.repoRoot),
+    })
+    if (verification.verificationHash !== pending.verificationHash) return toolResult(
+        'Architecture approval refused: graph evidence changed after preview; review a fresh preview.',
+        {state: 'GRAPH_CHANGED', wrote: false, previewVerificationHash: pending.verificationHash, currentVerificationHash: verification.verificationHash},
+    )
+    const boundary = createRepoBoundary(ctx?.repoRoot)
+    if (!boundary.root) return toolResult('Architecture approval refused: the repository boundary is unavailable.', {
+        state: 'PATH_REFUSED', wrote: false,
+    })
+    try { mkdirSync(join(boundary.root, '.weavatrix'), {recursive: true}) }
+    catch (error) { return toolResult(`Architecture approval could not create its policy directory: ${error.message}`, {
+        state: 'WRITE_FAILED', wrote: false, error: error.message,
+    }) }
+    const policyDirectory = boundary.resolve('.weavatrix')
+    if (!policyDirectory.ok) return toolResult('Architecture approval refused: the policy directory resolves outside the active repository.', {
+        state: 'PATH_REFUSED', wrote: false,
+    })
+    const targetPath = join(policyDirectory.path, 'architecture.json')
+    if (existsSync(targetPath)) return toolResult('Architecture approval refused: the target contract already exists.', {
+        state: 'ALREADY_CONFIGURED', wrote: false, source: '.weavatrix/architecture.json',
+    })
+    try {
+        writeFileSync(targetPath, pending.contents, {encoding: 'utf8', flag: 'wx'})
+    } catch (error) {
+        return toolResult(`Architecture approval failed without overwriting policy: ${error.message}`, {
+            state: 'WRITE_FAILED', wrote: false, error: error.message,
+        })
+    }
+    return toolResult(
+        `Architecture contract approved and created at .weavatrix/architecture.json (${pending.contentHash.slice(0, 12)}).`,
+        {state: 'APPROVED', wrote: true, source: '.weavatrix/architecture.json', contentHash: pending.contentHash, contract: pending.contract, verification},
+    )
+}
+
+export function tBootstrapArchitecture(g, args = {}, ctx) {
+    return args.action === 'approve' ? approve(g, args, ctx) : preview(g, args, ctx)
+}

package/src/mcp/architecture-starter.mjs

@@ -0,0 +1,234 @@
+// Adaptive, source-free architecture starter. It proposes component territories and separately
+// reports observed dependency directions; observations never become enforceable policy implicitly.
+import {normalizeArchitectureContract} from '../analysis/architecture-contract.js'
+import {createPathClassifier, hasPathClass} from '../path-classification.js'
+
+export const PROVISIONAL_BUDGETS = Object.freeze({
+    runtimeCycles: 0,
+    maxFileLoc: 300,
+    maxFunctionLoc: 120,
+    maxCyclomatic: 15,
+    maxModuleFiles: 80,
+    minModuleCohesion: .5,
+    maxModuleBoundaryRatio: .65,
+})
+
+export const STARTER_BUDGETS = Object.freeze({
+    runtimeCycles: PROVISIONAL_BUDGETS.runtimeCycles,
+    maxFileLoc: PROVISIONAL_BUDGETS.maxFileLoc,
+})
+
+const BUDGET_PROPOSALS = Object.freeze(Object.entries(PROVISIONAL_BUDGETS)
+    .filter(([key]) => !(key in STARTER_BUDGETS))
+    .map(([key, value]) => ({
+        key, value, state: 'CANDIDATE_NOT_ENFORCED',
+        reason: 'Generic review threshold; adopt only after inspecting repository-specific evidence.',
+    })))
+
+const SOURCE_ROOTS = new Set(['src', 'app', 'lib', 'packages', 'services'])
+const CODE_EXTENSIONS = new Set([
+    '.cjs', '.cs', '.css', '.go', '.htm', '.html', '.java', '.js', '.jsx', '.less', '.mjs', '.py', '.pyi',
+    '.rs', '.scss', '.ts', '.tsx',
+])
+const CLASSIFIED = ['test', 'e2e', 'generated', 'mock', 'story', 'docs', 'benchmark', 'temp']
+const EDGE_RELATIONS = new Set(['imports', 're_exports', 'calls', 'references'])
+
+const slash = (value) => String(value || '').replace(/\\/g, '/').replace(/^\.\//, '')
+const extension = (file) => {
+    const name = slash(file).split('/').at(-1) || ''
+    const dot = name.lastIndexOf('.')
+    return dot >= 0 ? name.slice(dot).toLowerCase() : ''
+}
+const safeId = (value, fallback) => String(value || '').toLowerCase()
+    .replace(/[^a-z0-9._:-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 100) || fallback
+
+function productFiles(graph, repoRoot) {
+    const classifier = createPathClassifier(repoRoot)
+    return [...new Set((graph?.nodes || [])
+        .filter((node) => !String(node.id).includes('#'))
+        .map((node) => slash(node.source_file || node.id))
+        .filter((file) => file && CODE_EXTENSIONS.has(extension(file))))]
+        .filter((file) => {
+            const explanation = classifier.explain(file)
+            return !explanation.excluded && !hasPathClass(explanation, ...CLASSIFIED)
+        })
+        .sort((a, b) => a.localeCompare(b))
+}
+
+function commonDirectoryPrefix(entries) {
+    if (!entries.length) return []
+    const first = entries[0].directories
+    let length = first.length
+    for (const entry of entries.slice(1)) {
+        let index = 0
+        while (index < length && index < entry.directories.length && first[index] === entry.directories[index]) index++
+        length = index
+    }
+    // Keep at least one package segment available as an actual component territory.
+    const shortest = Math.min(...entries.map((entry) => entry.directories.length))
+    return first.slice(0, Math.min(length, Math.max(0, shortest - 1)))
+}
+
+function javaTerritories(files) {
+    const byRoot = new Map()
+    for (const file of files) {
+        const match = /^(.*?)(?:\/)?src\/main\/java\/(.+\.java)$/i.exec(file)
+        if (!match) continue
+        const root = `${match[1] ? `${match[1]}/` : ''}src/main/java`
+        const tail = match[2].split('/')
+        const entry = {file, root, directories: tail.slice(0, -1)}
+        const entries = byRoot.get(root) || []
+        entries.push(entry)
+        byRoot.set(root, entries)
+    }
+    const paths = new Map()
+    for (const [root, entries] of byRoot) {
+        const common = commonDirectoryPrefix(entries)
+        for (const entry of entries) {
+            const next = entry.directories[common.length]
+            const path = next ? `${root}/${[...common, next].join('/')}` : entry.file
+            paths.set(entry.file, {key: path, name: path, path})
+        }
+    }
+    let refined = true
+    while (refined) {
+        refined = false
+        const groups = new Map()
+        for (const [file, territory] of paths) {
+            const entries = groups.get(territory.key) || []
+            entries.push({file, territory})
+            groups.set(territory.key, entries)
+        }
+        for (const entries of groups.values()) {
+            if (entries.length <= PROVISIONAL_BUDGETS.maxModuleFiles) continue
+            const base = entries[0].territory.path
+            if (!entries.every((entry) => entry.territory.path === base)) continue
+            const nested = entries.map((entry) => ({...entry, rest: entry.file.slice(base.length + 1).split('/')}))
+            const childDirectories = new Set(nested.filter((entry) => entry.rest.length > 1).map((entry) => entry.rest[0]))
+            if (childDirectories.size < 2) continue
+            for (const entry of nested) {
+                if (entry.rest.length > 1) {
+                    const path = `${base}/${entry.rest[0]}`
+                    paths.set(entry.file, {key: path, name: path, path})
+                } else {
+                    paths.set(entry.file, {key: `${base}::root`, name: `${base} (root files)`, path: entry.file})
+                }
+            }
+            refined = true
+        }
+    }
+    return paths
+}
+
+function nestedSourceTerritory(file) {
+    const match = /^(.*?)\/src\/(.+)$/.exec(file)
+    if (!match || !match[1]) return null
+    const tail = match[2].split('/')
+    // Java's src/main/java package tree is handled with a package-aware common prefix above.
+    if (tail[0] === 'main' && tail[1] === 'java') return null
+    return tail.length > 1 ? `${match[1]}/src/${tail[0]}` : file
+}
+
+function genericTerritory(file) {
+    const parts = file.split('/').filter(Boolean)
+    if (parts.length === 1) return {key: 'root-code', name: 'root code', path: file}
+    if (SOURCE_ROOTS.has(parts[0]) && parts.length === 2) {
+        return {key: `${parts[0]}-root`, name: `${parts[0]} (root files)`, path: file}
+    }
+    const path = parts.slice(0, SOURCE_ROOTS.has(parts[0]) ? 2 : 1).join('/')
+    return {key: path, name: path, path}
+}
+
+function componentsFor(graph, repoRoot) {
+    const files = productFiles(graph, repoRoot)
+    const java = javaTerritories(files)
+    const groups = new Map()
+    for (const file of files) {
+        const adaptive = java.get(file) || nestedSourceTerritory(file)
+        const territory = adaptive
+            ? typeof adaptive === 'string' ? {key: adaptive, name: adaptive, path: adaptive} : adaptive
+            : genericTerritory(file)
+        const group = groups.get(territory.key) || {name: territory.name, paths: new Set(), files: 0}
+        group.paths.add(territory.path)
+        group.files++
+        groups.set(territory.key, group)
+    }
+    return [...groups]
+        .sort((a, b) => b[1].files - a[1].files || a[0].localeCompare(b[0]))
+        .slice(0, 200)
+        .map(([key, group], index) => ({
+            id: safeId(key, `component-${index + 1}`),
+            name: group.name,
+            paths: [...group.paths].sort((a, b) => a.localeCompare(b)),
+        }))
+}
+
+function componentFor(file, components) {
+    const normalized = slash(file)
+    let best = null
+    for (const component of components) for (const prefix of component.paths) {
+        if (normalized !== prefix && !normalized.startsWith(`${prefix}/`)) continue
+        if (!best || prefix.length > best.prefix.length) best = {id: component.id, prefix}
+    }
+    return best?.id || null
+}
+
+const endpoint = (value) => value && typeof value === 'object' ? String(value.id) : String(value || '')
+function fileOf(id, byId) {
+    const node = byId.get(id)
+    return slash(node?.source_file || id.split('#')[0])
+}
+function edgeKind(link) {
+    return link.typeOnly === true ? 'type-only' : link.compileOnly === true ? 'compile-only' : 'runtime'
+}
+
+function observedDirections(graph, components) {
+    const byId = new Map((graph?.nodes || []).map((node) => [String(node.id), node]))
+    const pairs = new Set(), directions = new Map()
+    for (const link of graph?.links || []) {
+        if (!EDGE_RELATIONS.has(link.relation) || link.barrelProxy === true) continue
+        const fromFile = fileOf(endpoint(link.source), byId), toFile = fileOf(endpoint(link.target), byId)
+        const from = componentFor(fromFile, components), to = componentFor(toFile, components)
+        if (!from || !to || from === to) continue
+        const kind = edgeKind(link), pair = `${fromFile}\0${toFile}\0${kind}`
+        if (pairs.has(pair)) continue
+        pairs.add(pair)
+        const key = `${from}\0${to}\0${kind}`
+        const item = directions.get(key) || {from, to, kind, count: 0, samples: []}
+        item.count++
+        if (item.samples.length < 3) item.samples.push(`${fromFile} -> ${toFile}`)
+        directions.set(key, item)
+    }
+    return [...directions.values()]
+        .sort((a, b) => b.count - a.count || a.from.localeCompare(b.from) || a.to.localeCompare(b.to))
+        .slice(0, 100)
+        .map((item, index) => ({
+            ...item,
+            state: 'OBSERVED_NOT_ENFORCED',
+            suggestedRule: {
+                id: safeId(`observed-${item.from}-to-${item.to}-${item.kind}`, `observed-${index + 1}`),
+                action: 'allow', kinds: [item.kind], from: [item.from], to: [item.to],
+                reason: `Observed in ${item.count} unique file dependency pair(s); review before adopting as policy.`,
+            },
+        }))
+}
+
+export function proposeObservedDependencyDirections(graph, components) {
+    return observedDirections(graph, components)
+}
+
+export function createArchitectureStarter(graph, repoRoot) {
+    const components = componentsFor(graph, repoRoot)
+    const contract = normalizeArchitectureContract({
+        name: 'Proposed no-regressions baseline', style: 'custom', enforcement: 'ratchet', components,
+        dependencyRules: [], budgets: STARTER_BUDGETS,
+        technologies: {required: [], forbidden: []}, exceptions: [],
+        ratchet: {baseline: {fingerprints: [], metrics: {}}},
+    })
+    return {
+        contract,
+        observedDependencyProposals: proposeObservedDependencyDirections(graph, contract.components),
+        budgetProposals: BUDGET_PROPOSALS,
+        methodology: 'adaptive product territories; only universal runtime-cycle/file-size guards are active; observed directions and generic quality thresholds are review-only',
+    }
+}