weavatrix 0.1.3 → 0.2.0

package/skill/SKILL.md

@@ -1,13 +1,14 @@
 ---
 name: weavatrix
-description: Drive the weavatrix MCP — code graph, blast-radius (get_dependents/change_impact), health audit, duplicates, coverage, endpoints — over any local repo. Use when analyzing code structure, refactor risk, dead code, dependency health, or before opening a PR.
+description: Drive the weavatrix MCP — code graph, blast-radius (get_dependents/change_impact), dead-code review, health audit, duplicates, coverage, endpoints — over any local repo. Use when analyzing code structure, refactor risk, dead code, dependency health, or before opening a PR.
 ---
 
 # weavatrix MCP
 
 Structure-analysis tools over a prebuilt code graph plus the weavatrix analysis engines. The default
-is offline and includes `open_repo` for one-call switching between local Git repositories. A custom
-capability list that omits `retarget` pins the registration to its initial repository.
+`offline` profile has every HTTP tool disabled and permits repository switching only through an
+explicit local `open_repo` call. Use `pinned` when a shared MCP process must never change or inspect
+outside its startup repository.
 
 ## Step 0 — if the tools are missing
 
@@ -15,45 +16,71 @@ Tools are named `mcp__weavatrix__…`. If none are available, ask the user to re
 (`claude mcp add -s user weavatrix -- npx -y weavatrix <repoRoot>`; Codex:
 `codex mcp add weavatrix -- npx -y weavatrix <repoRoot>`), then retry.
 
-If only `refresh_advisories` or `sync_graph` is missing, do not diagnose a broken installation:
-`online` is intentionally absent from the default capability list.
+If `refresh_advisories`, `pull_architecture_contract`, or `sync_graph` is missing, do not diagnose a
+broken installation: network tools are intentionally absent from `offline` and `pinned`.
+
+Profiles use the same npm package and binary:
+
+- `offline` (default): all local analysis and explicit `open_repo`; no HTTP tools.
+- `pinned`: local analysis with no `open_repo`, no global/cross-repository graph access, and no HTTP tools.
+- `osv`: `offline` plus explicit `refresh_advisories`.
+- `hosted` / `full`: `osv` plus `pull_architecture_contract` and `sync_graph`.
+
+The legacy `online` capability remains a compatibility alias for `advisories,hosted`; prefer the
+named profiles for new registrations.
 
 ## Ground rules
 
 - **Evidence, not verdicts**: treat audit, hub, orphan and duplicate output as hypotheses. Confirm a
   finding in source and check framework/runtime conventions before deleting, merging or redesigning
   code. A same-name/different-body pair is a divergence candidate, not proof of duplication.
-- **Freshness**: every graph tool appends a staleness warning when the repo has commits newer than
-  the graph. Act on it: `rebuild_graph`. A normal `open_repo` builds missing graphs and upgrades
-  pre-`0.1.3` graphs to typed import edges; `build:false` deliberately refuses that upgrade.
+- **Freshness**: graph/health calls automatically reconcile the active graph, while cross-repository
+  tracing reconciles every selected registered graph. Read the structured `refresh` /
+  `graphReconciliation` status: `none`, `incremental`, `full`, or explicitly `PARTIAL`. Use
+  `rebuild_graph` only when automatic reconciliation reports a fallback/error or when intentionally
+  changing build mode. A normal `open_repo` builds missing graphs and upgrades legacy schemas;
+  `build:false` deliberately refuses that upgrade.
 - **Ambiguity**: `get_node`/`get_neighbors`/`get_dependents` disclose `matched N nodes; using the
   best-connected` — read that note before trusting the answer; pass an exact node id to pin it.
-- **Runtime versus compile time**: keep runtime cycles and TypeScript type-only coupling separate.
-  `module_map` and `change_impact` label the distinction; `god_nodes` ranks unique connectivity and
-  reports repeated references separately. Do not schedule a runtime-cycle refactor from type-only
-  edges alone.
+- **Runtime versus compile time**: keep runtime cycles separate from TypeScript type-only and
+  language compile-only coupling (Rust `mod`/`use`/`pub use`, Java imports). `module_map`,
+  `change_impact` and `graph_diff` label the distinction; `god_nodes` ranks unique connectivity and
+  reports repeated references separately. Do not schedule a runtime-cycle refactor from
+  compile-time-only edges.
 - **Repository universe**: in Git repositories, graph and duplicate scans include tracked plus
   non-ignored untracked files. If an old graph still contains packaged/generated output, rebuild it
-  before interpreting the result.
+  before interpreting the result. Repository-root `.weavatrixignore` applies the same tracked-file
+  exclusions to graph, audit and duplicate passes; use it for generated/e2e fixtures that must stay
+  committed. `no-tests` also recognizes Cypress, Playwright, `test-e2e`, acceptance and integration
+  roots. Dead-code/clone/audit review also suppresses `benchmarks/**` and `**/__temp/**` as classified
+  non-production surfaces. A verified production benchmark can opt back in narrowly through
+  `.weavatrix.json` `classify.product`, for example `{"classify":{"product":["benchmarks/core/**"]}}`.
+- **Architectural queries**: for bootstrap/routing/authentication questions, inspect the returned
+  seeds before trusting the traversal. Pass exact repository-relative `seed_files` to `query_graph`
+  when the intended entry points are already known.
 - **Coverage**: `coverage_map` reads an existing report. `unavailable` means no supported report was
   found, not 0% coverage; do not rank testing risk from that state.
 - **Audit completeness**: read `checks.osv.status` and `checks.malware.status`. For OSV, `OK` is
   complete for the recorded dependency fingerprint; `PARTIAL` is incomplete or stale,
   `NOT_CHECKED` has no repository-specific result, and `ERROR` means the local check failed. Treat
   the same non-`OK` states as incomplete for malware scanning. Refresh OSV only when the user has
-  authorized adding the optional `online` capability group to the MCP registration and then
+  authorized selecting the optional `osv` profile (or `advisories` capability) and then
   invoking `refresh_advisories`; enabling the group alone sends nothing.
 - **Offline by design**: scans and graph queries run in-process against local files; coverage tools
-  read existing reports and never run tests. The ONLY network-touching tools live in the `online`
-  capability group and run solely when explicitly called: `refresh_advisories` (queries OSV.dev with
-  package names + versions so `run_audit` has fresh vulnerability data) and `sync_graph` (pushes a
-  versioned allowlist of graph metadata, discarding unknown fields and never reading source file
-  bodies for sync, to a user-configured endpoint; disabled until
-  `WEAVATRIX_SYNC_URL` is set). `online` is
-  absent from the default capability set and must be enabled explicitly.
+  read existing reports and never run tests. The ONLY network-touching tools live in the optional
+  `advisories` / `hosted` capabilities and run solely when explicitly called:
+  `refresh_advisories` (queries OSV.dev with
+  package names + versions so `run_audit` has fresh vulnerability data) and `sync_graph` (derives a
+  bounded evidence snapshot locally, then pushes only an allowlisted graph/evidence contract to a
+  user-configured endpoint; analyzers may read local source, but the wire contract has no body,
+  snippet, absolute-host-path or environment fields, and unknown fields are discarded; disabled until
+  `WEAVATRIX_SYNC_URL` is set). `pull_architecture_contract` sends only the active repository's opaque
+  stable UUID, downloads the owner-approved contract, validates it, and caches it locally; it requires
+  `WEAVATRIX_SYNC_URL` and `WEAVATRIX_SYNC_TOKEN`. All three are absent from the default profile.
 - **Repository boundary**: source reads and graph-derived paths are realpath-contained. `open_repo`
-  intentionally changes the active boundary through an explicit offline tool call. It is available
-  by default; omit `retarget` from a custom capability list to hide it.
+  intentionally changes the active boundary through an explicit offline tool call. It is included in
+  `offline`, absent from `pinned`, and available in a custom registration only when `retarget` is
+  named. Concurrent non-mutating calls retain the graph/root snapshot with which they started.
 
 ## Recipes
 
@@ -64,12 +91,37 @@ If only `refresh_advisories` or `sync_graph` is missing, do not diagnose a broke
   and untracked work, coverage attached, untested hotspots called out) → drill with `get_dependents`.
 - **Impact of a PR that is NOT checked out**: pass its changed-file list explicitly —
   `change_impact files=[…]` — same blast-radius + coverage view, no checkout.
-- **Validate a refactor structurally**: edit → `rebuild_graph` — it reports the structural delta
-  (cycle broken? new module dependency introduced? symbols orphaned?); re-query later with
-  `graph_diff` (optionally scoped by `path`). The semantic complement to the textual git diff.
-- **Health sweep**: `run_audit` (filter by `category`/`min_severity`) → `find_duplicates` →
-  `coverage_map`. Inspect the source behind shortlisted findings before proposing edits.
-- **API inventory**: `list_endpoints`.
+- **Validate a refactor structurally**: call `graph_diff base_ref=HEAD~1` (or `main` / `origin/main`)
+  to build an immutable baseline without checkout and compare it with the current graph. Alternatively,
+  edit → `rebuild_graph`, then use `graph_diff` without `base_ref` to compare `graph.prev.json` with
+  the rebuilt graph. Either route can be scoped by `path`; look for cycle, module-dependency and
+  orphan drift rather than raw edge counts.
+- **Health sweep**: for a branch/PR review prefer
+  `run_audit base_ref=<merge-base> debt=new changed_files=[…]`; for repository maintenance use
+  `run_audit debt=all`. Then call `find_dead_code`, `find_duplicates` and `coverage_map`. A changed-file-only audit is
+  scope, not proof of new debt. Inspect the source behind shortlisted findings before proposing edits.
+- **Dead-code and dead-method review**: call `find_dead_code` for a bounded production-code queue of
+  files, functions, methods and symbols. Narrow with `path` or `kinds=["method"]`; keep the default
+  `min_confidence=medium` for actionable internal candidates. Use `min_confidence=low` only when the
+  task explicitly needs public/exported, framework, dynamic-loading or reflection-sensitive review,
+  and carry each returned caveat into the recommendation. Pair it with
+  `run_audit category=unused debt=all` (or `base_ref=<merge-base> debt=new`) for unused exports and
+  dependencies. Before deletion, run `read_source`, `get_dependents`, exact `search_code`, inspect
+  framework discovery/annotations, package scripts, CLI/Docker/manifests, generated consumers and
+  test-only use, then run the repository tests. `REVIEW_REQUIRED` and `autoDelete:false` are hard
+  safety semantics, not boilerplate. Use `.weavatrix-deps.json` entrypoints/nonRuntimeRoots only for
+  verified conventions.
+- **API inventory**: `list_endpoints` (including Next.js App Router, Rust axum and actix-web).
+- **Cross-repository API impact**: ensure both repositories are in `list_known_repos`, then call
+  `trace_api_contract backend=<uuid-or-label> clients=[<uuid-or-label>]`; narrow with `method`, `path`,
+  or backend `changed_files`. Treat unresolved/dynamic URLs as incomplete evidence, not a clean result.
+- **Target architecture before editing**: `get_architecture_contract` → `prepare_change` with the
+  intended files → edit and rebuild → `verify_architecture`. A missing contract returns a starter
+  proposal, not an automatically approved architecture. Pull an owner-approved hosted contract only
+  when the user selected `hosted` and explicitly asks for it.
+- **Behavioral architecture**: `git_history` ranks churn × connectivity hotspots and hidden
+  co-change coupling from bounded local numstat history. Use it as review evidence, not proof that two
+  files must be merged.
 - **Find code**: `search_code` (regex + glob) → `get_node` → `read_source`.
 - **Another repo**: `list_known_repos` → `open_repo <path>`
   (builds or upgrades the graph when needed; `build:false` probes without building).
@@ -77,13 +129,15 @@ If only `refresh_advisories` or `sync_graph` is missing, do not diagnose a broke
 ## Repository-specific conventions
 
 Weavatrix understands nearest workspace manifests, nested `tsconfig`/`jsconfig` aliases,
-framework-owned runtime peers such as Next.js + `react-dom`, and Next.js App Router route exports.
-For project-specific entry points or Python dependencies supplied by an external runtime, add
-`.weavatrix-deps.json` at the repository root:
+framework-owned runtime peers such as Next.js + `react-dom`, generated NAPI-RS platform loaders,
+and Next.js App Router route exports. For project-specific entry points, reusable template catalogs,
+or Python dependencies supplied by an external runtime, add `.weavatrix-deps.json` at the repository
+root:
 
 ```json
 {
   "entrypoints": ["scripts/publish-release.mjs"],
+  "nonRuntimeRoots": ["library", "catalogs/examples"],
   "python": {
     "managedDependencies": ["numpy", "openvino-genai"],
     "ignoreDependencies": ["vendor-sdk"]
@@ -91,22 +145,37 @@ For project-specific entry points or Python dependencies supplied by an external
 }
 ```
 
-Keep exceptions narrow. `managedDependencies` documents modules provided outside the repo's Python
-manifest; `ignoreDependencies` suppresses intentionally unresolved imports.
+Keep exceptions narrow. `nonRuntimeRoots` (alias `templateRoots`) marks reusable examples that are
+not one deployed application. It suppresses orphan/dead/unused-export noise and missing/unresolved
+dependency findings when every use is inside those roots; graph edges, cycles and boundaries remain
+visible. `managedDependencies` documents modules provided outside the repo's Python manifest;
+`ignoreDependencies` suppresses intentionally unresolved imports.
 
 ## Sync
 
-`sync_graph` uses allowlisted payload v2, including typed-edge metadata but no source bodies. A graph
-built before `0.1.3` must be rebuilt first; normal `open_repo` does this automatically. Sync remains
-unavailable until the user opts into `online` and configures `WEAVATRIX_SYNC_URL`.
+`sync_graph` defaults to payload v3: graph metadata plus deterministic architecture, health, stack,
+package-dependency and clone-review evidence. Read each section's `state`, `verdict` and completeness counts; `PARTIAL`,
+`NOT_CHECKED` and `ERROR` are unknown/incomplete, never a clean result. Architecture evidence
+contains concrete runtime versus compile-time cycles, declared boundary violations and separated
+runtime/type-only/compile-only module dependencies. Package evidence contains a bounded lockfile
+graph with direct/transitive runtime, dev, optional and peer edges plus explicit resolution counts.
+Duplicate evidence contains stable, source-free clone/divergence candidates; it never sends method
+bodies or snippets. Use `payload_version: 2` only when the user explicitly wants graph-only
+compatibility—Weavatrix never silently downgrades. A graph built before `0.1.4`, or one stale against
+the working tree, must be rebuilt first. Sync remains unavailable until the user selects `hosted`
+(or the exact `hosted` capability) and configures `WEAVATRIX_SYNC_URL`.
 
 ## Troubleshooting
 
-- `Graph unavailable` → `rebuild_graph`; `open_repo` can select another valid repository path unless
+- `Graph unavailable` → `rebuild_graph`; normal graph/health calls automatically refresh an existing
+  graph and report `none`, `incremental`, or `full`. `open_repo` can select another valid repository path unless
   the registration deliberately omitted `retarget`.
 - `refresh_advisories` is unavailable → with the user's approval, re-register/reconfigure the MCP
-  capability list to include `online`, reconnect it, and then invoke the tool. Do not enable network
+  with the `osv` profile, reconnect it, and then invoke the tool. Do not enable network
   access merely to turn `NOT_CHECKED` into a cosmetic green state.
+- `pull_architecture_contract` / `sync_graph` is unavailable → use the `hosted` profile only after
+  the user chooses hosted integration; configure `WEAVATRIX_SYNC_URL` and a bearer token for contract
+  pull. Profile selection alone never performs a request.
 - `No coverage report` → run the repo's own tests with coverage (`vitest run --coverage`,
   `jest --coverage`, `pytest --cov --cov-report=json`, `go test -coverprofile=coverage.out`),
   then re-call.

package/src/analysis/architecture-contract.js

@@ -0,0 +1,343 @@
+// Executable target-architecture contract and no-regressions ratchet.
+// The contract contains selectors and budgets only; verification is pure over graph metadata and never
+// needs source bodies. Fingerprints deliberately exclude line numbers so edits do not churn baselines.
+import {createHash} from 'node:crypto'
+import {existsSync, readFileSync, writeFileSync, mkdirSync} from 'node:fs'
+import {dirname, join} from 'node:path'
+import {createRepoBoundary} from '../repo-path.js'
+
+export const ARCHITECTURE_CONTRACT_V = 1
+export const CONTRACT_PATHS = ['.weavatrix/architecture.json', '.weavatrix-architecture.json']
+
+const RELATION_KIND = new Set(['runtime', 'type-only', 'compile-only', 'any'])
+const ACTION = new Set(['allow', 'forbid'])
+const ENFORCEMENT = new Set(['ratchet', 'strict', 'advisory'])
+const safeId = (value, fallback = '') => {
+    const text = String(value ?? '').trim()
+    return /^[a-z0-9][a-z0-9._:-]{0,127}$/i.test(text) ? text : fallback
+}
+const pathPrefix = (value) => {
+    const text = String(value ?? '').replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+|\/+$/g, '')
+    return text && !text.split('/').some((part) => !part || part === '.' || part === '..') ? text : null
+}
+const stringList = (value, sanitize, cap = 100) => [...new Set((Array.isArray(value) ? value : [])
+    .slice(0, cap).map(sanitize).filter(Boolean))]
+const finiteBudget = (value, fallback = null) => {
+    const number = Number(value)
+    return Number.isFinite(number) && number >= 0 ? number : fallback
+}
+const endpoint = (value) => value && typeof value === 'object' ? String(value.id) : String(value ?? '')
+const isSymbol = (id) => String(id).includes('#')
+const fileOf = (id, byId) => {
+    const node = byId.get(String(id))
+    if (node?.source_file) return String(node.source_file).replace(/\\/g, '/')
+    return String(id).split('#')[0].replace(/\\/g, '/')
+}
+const stable = (value) => Array.isArray(value)
+    ? `[${value.map(stable).join(',')}]`
+    : value && typeof value === 'object'
+        ? `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stable(value[key])}`).join(',')}}`
+        : JSON.stringify(value)
+const hash = (value) => createHash('sha256').update(stable(value)).digest('hex')
+
+function sanitizeComponent(value, index) {
+    const id = safeId(value?.id, `component-${index + 1}`)
+    const paths = stringList(value?.paths ?? [value?.path], pathPrefix, 64)
+    if (!paths.length) return null
+    return {id, name: String(value?.name || id).slice(0, 128), paths}
+}
+
+function sanitizeRule(value, index) {
+    const from = stringList(value?.from, (item) => item === '*' ? '*' : safeId(item), 64)
+    const to = stringList(value?.to, (item) => item === '*' ? '*' : safeId(item), 64)
+    if (!from.length || !to.length) return null
+    return {
+        id: safeId(value?.id, `dependency-${index + 1}`),
+        action: ACTION.has(value?.action) ? value.action : 'forbid',
+        kinds: stringList(value?.kinds ?? ['runtime'], (kind) => RELATION_KIND.has(kind) ? kind : '', 4),
+        from,
+        to,
+        ...(value?.reason ? {reason: String(value.reason).slice(0, 300)} : {}),
+    }
+}
+
+function sanitizeException(value) {
+    const fingerprint = /^[a-f0-9]{16,64}$/i.test(String(value?.fingerprint || '')) ? String(value.fingerprint) : null
+    if (!fingerprint) return null
+    const expires = /^\d{4}-\d{2}-\d{2}$/.test(String(value?.expires || '')) ? String(value.expires) : null
+    return {fingerprint, reason: String(value?.reason || '').slice(0, 300), ...(expires ? {expires} : {})}
+}
+
+export function normalizeArchitectureContract(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input)) throw new Error('architecture contract must be an object')
+    const components = (Array.isArray(input.components) ? input.components : [])
+        .slice(0, 200).map(sanitizeComponent).filter(Boolean)
+    const componentIds = new Set(components.map((item) => item.id))
+    const dependencyRules = (Array.isArray(input.dependencyRules) ? input.dependencyRules : [])
+        .slice(0, 500).map(sanitizeRule).filter(Boolean)
+        .filter((rule) => [...rule.from, ...rule.to].every((id) => id === '*' || componentIds.has(id)))
+    const rawBudgets = input.budgets && typeof input.budgets === 'object' ? input.budgets : {}
+    const budgets = {
+        runtimeCycles: finiteBudget(rawBudgets.runtimeCycles),
+        maxFunctionLoc: finiteBudget(rawBudgets.maxFunctionLoc),
+        maxFileLoc: finiteBudget(rawBudgets.maxFileLoc),
+        maxCyclomatic: finiteBudget(rawBudgets.maxCyclomatic),
+        maxParams: finiteBudget(rawBudgets.maxParams),
+        maxRuntimeDependenciesPerComponent: finiteBudget(rawBudgets.maxRuntimeDependenciesPerComponent),
+        maxModuleFiles: finiteBudget(rawBudgets.maxModuleFiles),
+        minModuleCohesion: finiteBudget(rawBudgets.minModuleCohesion),
+        maxModuleBoundaryRatio: finiteBudget(rawBudgets.maxModuleBoundaryRatio),
+    }
+    for (const key of Object.keys(budgets)) if (budgets[key] == null) delete budgets[key]
+    const technologies = {
+        required: stringList(input.technologies?.required, (item) => safeId(item), 100),
+        forbidden: stringList(input.technologies?.forbidden, (item) => safeId(item), 100),
+    }
+    const baseline = input.ratchet?.baseline && typeof input.ratchet.baseline === 'object'
+        ? {
+            fingerprints: stringList(input.ratchet.baseline.fingerprints, (item) => /^[a-f0-9]{16,64}$/i.test(String(item)) ? String(item) : '', 5_000),
+            metrics: Object.fromEntries(Object.entries(input.ratchet.baseline.metrics || {}).slice(0, 500)
+                .map(([key, value]) => [safeId(key), finiteBudget(value)]).filter(([key, value]) => key && value != null)),
+        }
+        : {fingerprints: [], metrics: {}}
+    const contract = {
+        architectureContractV: ARCHITECTURE_CONTRACT_V,
+        name: String(input.name || 'Target architecture').slice(0, 128),
+        style: safeId(input.style, 'custom'),
+        enforcement: ENFORCEMENT.has(input.enforcement) ? input.enforcement : 'ratchet',
+        components,
+        dependencyRules,
+        budgets,
+        technologies,
+        exceptions: (Array.isArray(input.exceptions) ? input.exceptions : []).slice(0, 500).map(sanitizeException).filter(Boolean),
+        ratchet: {baseline},
+    }
+    return {...contract, contractHash: hash(contract)}
+}
+
+export function loadArchitectureContract(repoRoot, graphPath) {
+    const boundary = createRepoBoundary(repoRoot)
+    for (const relative of CONTRACT_PATHS) {
+        const resolved = boundary.resolve(relative)
+        if (!resolved.ok || !existsSync(resolved.path)) continue
+        try { return {contract: normalizeArchitectureContract(JSON.parse(readFileSync(resolved.path, 'utf8'))), source: relative} }
+        catch (error) { return {contract: null, source: relative, error: error.message} }
+    }
+    const cached = graphPath ? join(dirname(graphPath), 'architecture.contract.json') : null
+    if (cached && existsSync(cached)) {
+        try { return {contract: normalizeArchitectureContract(JSON.parse(readFileSync(cached, 'utf8'))), source: 'hosted-cache'} }
+        catch (error) { return {contract: null, source: 'hosted-cache', error: error.message} }
+    }
+    return {contract: null, source: null, error: null}
+}
+
+export function writeCachedArchitectureContract(graphPath, input) {
+    if (!graphPath) throw new Error('graph path is required for hosted contract cache')
+    const contract = normalizeArchitectureContract(input)
+    const path = join(dirname(graphPath), 'architecture.contract.json')
+    mkdirSync(dirname(path), {recursive: true})
+    writeFileSync(path, JSON.stringify(contract, null, 2), 'utf8')
+    return {path, contract}
+}
+
+function componentFor(file, components) {
+    const normalized = String(file || '').replace(/\\/g, '/')
+    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 || '(unmapped)'
+}
+
+function relationKind(link) {
+    if (link.typeOnly === true) return 'type-only'
+    if (link.compileOnly === true) return 'compile-only'
+    return 'runtime'
+}
+
+function runtimeFileGraph(graph) {
+    const byId = new Map((graph.nodes || []).map((node) => [String(node.id), node]))
+    const files = new Set((graph.nodes || []).filter((node) => !isSymbol(node.id)).map((node) => String(node.id)))
+    const adjacency = new Map([...files].map((file) => [file, new Set()]))
+    for (const link of graph.links || []) {
+        if (relationKind(link) !== 'runtime' || !['imports', 're_exports'].includes(link.relation) || link.barrelProxy === true) continue
+        const source = fileOf(endpoint(link.source), byId)
+        const target = fileOf(endpoint(link.target), byId)
+        if (source && target && source !== target && files.has(source) && files.has(target)) adjacency.get(source)?.add(target)
+    }
+    return adjacency
+}
+
+function stronglyConnected(adjacency) {
+    let index = 0
+    const indexes = new Map(), low = new Map(), stack = [], onStack = new Set(), out = []
+    const visit = (node) => {
+        indexes.set(node, index); low.set(node, index); index++; stack.push(node); onStack.add(node)
+        for (const target of adjacency.get(node) || []) {
+            if (!indexes.has(target)) { visit(target); low.set(node, Math.min(low.get(node), low.get(target))) }
+            else if (onStack.has(target)) low.set(node, Math.min(low.get(node), indexes.get(target)))
+        }
+        if (low.get(node) !== indexes.get(node)) return
+        const component = []
+        while (stack.length) { const value = stack.pop(); onStack.delete(value); component.push(value); if (value === node) break }
+        if (component.length > 1 || adjacency.get(node)?.has(node)) out.push(component.sort())
+    }
+    for (const node of [...adjacency.keys()].sort()) if (!indexes.has(node)) visit(node)
+    return out.sort((a, b) => b.length - a.length || a[0].localeCompare(b[0]))
+}
+
+function violation(ruleId, kind, evidence, current, target) {
+    const normalizedEvidence = String(evidence).replace(/:\d+(?=\b|$)/g, '')
+    const fingerprint = hash({ruleId, kind, evidence: normalizedEvidence}).slice(0, 32)
+    return {fingerprint, ruleId, kind, evidence, ...(current != null ? {current} : {}), ...(target != null ? {target} : {})}
+}
+
+function matchSelector(selector, value) { return selector.includes('*') || selector.includes(value) }
+
+export function verifyArchitecture({graph, contract: rawContract, technologies = []}) {
+    const contract = rawContract?.contractHash ? rawContract : normalizeArchitectureContract(rawContract)
+    const nodes = Array.isArray(graph?.nodes) ? graph.nodes : []
+    const links = Array.isArray(graph?.links) ? graph.links : []
+    const byId = new Map(nodes.map((node) => [String(node.id), node]))
+    const exceptions = new Set(contract.exceptions
+        .filter((item) => !item.expires || item.expires >= new Date().toISOString().slice(0, 10))
+        .map((item) => item.fingerprint))
+    const violations = []
+    const componentEdges = new Map()
+    for (const link of links) {
+        if (!['imports', 're_exports', 'calls', 'references'].includes(link.relation) || link.barrelProxy === true) continue
+        const fromFile = fileOf(endpoint(link.source), byId), toFile = fileOf(endpoint(link.target), byId)
+        if (!fromFile || !toFile || fromFile === toFile) continue
+        const from = componentFor(fromFile, contract.components), to = componentFor(toFile, contract.components)
+        if (from === to) continue
+        const kind = relationKind(link)
+        const key = `${from}\0${to}\0${kind}`
+        const record = componentEdges.get(key) || {from, to, kind, count: 0, samples: []}
+        record.count++
+        if (record.samples.length < 5) record.samples.push(`${fromFile} -> ${toFile}`)
+        componentEdges.set(key, record)
+    }
+    for (const edge of componentEdges.values()) {
+        const applicable = contract.dependencyRules.filter((rule) =>
+            rule.kinds.some((kind) => kind === 'any' || kind === edge.kind) && matchSelector(rule.from, edge.from))
+        for (const rule of applicable) {
+            if (rule.action === 'forbid' && matchSelector(rule.to, edge.to)) {
+                violations.push(violation(rule.id, 'dependency', `${edge.from} -> ${edge.to} (${edge.kind})`, edge.count, 0))
+            }
+        }
+        const allowRules = applicable.filter((rule) => rule.action === 'allow')
+        if (allowRules.length && !allowRules.some((rule) => matchSelector(rule.to, edge.to))) {
+            const ruleId = allowRules.map((rule) => rule.id).sort().join('+')
+            violations.push(violation(ruleId, 'dependency', `${edge.from} -> ${edge.to} (${edge.kind}; outside allow-list)`, edge.count, 0))
+        }
+    }
+    const runtimeCycles = stronglyConnected(runtimeFileGraph(graph))
+    if (contract.budgets.runtimeCycles != null && runtimeCycles.length > contract.budgets.runtimeCycles) {
+        violations.push(violation('budget.runtimeCycles', 'budget', `runtime cycles: ${runtimeCycles.length}`, runtimeCycles.length, contract.budgets.runtimeCycles))
+    }
+    const componentRuntimeTargets = new Map()
+    for (const edge of componentEdges.values()) if (edge.kind === 'runtime') {
+        const targets = componentRuntimeTargets.get(edge.from) || new Set(); targets.add(edge.to); componentRuntimeTargets.set(edge.from, targets)
+    }
+    if (contract.budgets.maxRuntimeDependenciesPerComponent != null) for (const [component, targets] of componentRuntimeTargets) {
+        if (targets.size > contract.budgets.maxRuntimeDependenciesPerComponent) violations.push(violation(
+            'budget.maxRuntimeDependenciesPerComponent', 'budget', `${component} runtime dependencies`, targets.size,
+            contract.budgets.maxRuntimeDependenciesPerComponent,
+        ))
+    }
+    const componentStats = new Map(contract.components.map((component) => [component.id, {
+        files: new Set(), internalPairs: new Set(), boundaryPairs: new Set(),
+    }]))
+    for (const node of nodes.filter((item) => !isSymbol(item.id))) {
+        const file = String(node.source_file || node.id).replace(/\\/g, '/')
+        const component = componentFor(file, contract.components)
+        componentStats.get(component)?.files.add(file)
+    }
+    const runtimePairs = new Set()
+    for (const link of links) {
+        if (relationKind(link) !== 'runtime' || !['imports', 're_exports', 'calls', 'references'].includes(link.relation) || link.barrelProxy === true) continue
+        const source = fileOf(endpoint(link.source), byId), target = fileOf(endpoint(link.target), byId)
+        if (!source || !target || source === target) continue
+        const pair = `${source}\0${target}`
+        if (runtimePairs.has(pair)) continue
+        runtimePairs.add(pair)
+        const from = componentFor(source, contract.components), to = componentFor(target, contract.components)
+        if (from === to) componentStats.get(from)?.internalPairs.add(pair)
+        else {
+            componentStats.get(from)?.boundaryPairs.add(pair)
+            componentStats.get(to)?.boundaryPairs.add(pair)
+        }
+    }
+    for (const [component, stats] of componentStats) {
+        const internal = stats.internalPairs.size, boundary = stats.boundaryPairs.size
+        const cohesion = internal + boundary ? internal / (internal + boundary) : 1
+        const boundaryRatio = internal + boundary ? boundary / (internal + boundary) : 0
+        if (contract.budgets.maxModuleFiles != null && stats.files.size > contract.budgets.maxModuleFiles) violations.push(violation('budget.maxModuleFiles', 'budget', `${component} files`, stats.files.size, contract.budgets.maxModuleFiles))
+        if (contract.budgets.minModuleCohesion != null && cohesion < contract.budgets.minModuleCohesion) violations.push(violation('budget.minModuleCohesion', 'budget', `${component} cohesion`, Number(cohesion.toFixed(4)), contract.budgets.minModuleCohesion))
+        if (contract.budgets.maxModuleBoundaryRatio != null && boundaryRatio > contract.budgets.maxModuleBoundaryRatio) violations.push(violation('budget.maxModuleBoundaryRatio', 'budget', `${component} boundary ratio`, Number(boundaryRatio.toFixed(4)), contract.budgets.maxModuleBoundaryRatio))
+    }
+    for (const node of nodes) {
+        const loc = finiteBudget(node?.complexity?.loc)
+        const cyclomatic = finiteBudget(node?.complexity?.cyclomatic)
+        const params = finiteBudget(node?.complexity?.params)
+        const evidence = `${node.source_file || fileOf(node.id, byId)}#${node.label || node.id}`
+        if (contract.budgets.maxFunctionLoc != null && loc != null && loc > contract.budgets.maxFunctionLoc) violations.push(violation('budget.maxFunctionLoc', 'budget', evidence, loc, contract.budgets.maxFunctionLoc))
+        if (contract.budgets.maxCyclomatic != null && cyclomatic != null && cyclomatic > contract.budgets.maxCyclomatic) violations.push(violation('budget.maxCyclomatic', 'budget', evidence, cyclomatic, contract.budgets.maxCyclomatic))
+        if (contract.budgets.maxParams != null && params != null && params > contract.budgets.maxParams) violations.push(violation('budget.maxParams', 'budget', evidence, params, contract.budgets.maxParams))
+    }
+    if (contract.budgets.maxFileLoc != null) for (const node of nodes.filter((item) => !isSymbol(item.id))) {
+        const file = String(node.source_file || node.id)
+        const maxEnd = nodes.filter((item) => item.source_file === file && isSymbol(item.id))
+            .reduce((max, item) => Math.max(max, Number(String(item.source_end || '').replace(/^L/, '')) || 0), 0)
+        if (maxEnd > contract.budgets.maxFileLoc) violations.push(violation('budget.maxFileLoc', 'budget', file, maxEnd, contract.budgets.maxFileLoc))
+    }
+    const techSet = new Set(technologies.map((item) => safeId(item)).filter(Boolean))
+    for (const required of contract.technologies.required) if (!techSet.has(required)) violations.push(violation('technology.required', 'technology', `missing ${required}`))
+    for (const forbidden of contract.technologies.forbidden) if (techSet.has(forbidden)) violations.push(violation('technology.forbidden', 'technology', `forbidden ${forbidden}`))
+
+    const active = violations.filter((item) => !exceptions.has(item.fingerprint))
+    const baseline = new Set(contract.ratchet.baseline.fingerprints)
+    const current = new Set(active.map((item) => item.fingerprint))
+    const fresh = active.filter((item) => !baseline.has(item.fingerprint))
+    const existing = active.filter((item) => baseline.has(item.fingerprint))
+    const fixed = [...baseline].filter((fingerprint) => !current.has(fingerprint))
+    const status = contract.enforcement === 'advisory'
+        ? 'ADVISORY'
+        : contract.enforcement === 'strict'
+            ? (active.length ? 'FAIL' : 'PASS')
+            : (fresh.length ? 'FAIL' : 'PASS')
+    const metrics = {
+        runtimeCycles: runtimeCycles.length,
+        violations: active.length,
+        componentDependencies: componentEdges.size,
+        mappedComponents: contract.components.length,
+        componentFitness: Object.fromEntries([...componentStats].map(([component, stats]) => {
+            const internal = stats.internalPairs.size, boundary = stats.boundaryPairs.size
+            return [component, {files: stats.files.size, cohesion: internal + boundary ? Number((internal / (internal + boundary)).toFixed(4)) : 1, boundaryRatio: internal + boundary ? Number((boundary / (internal + boundary)).toFixed(4)) : 0}]
+        })),
+    }
+    const result = {
+        architectureVerificationV: 1,
+        contractHash: contract.contractHash,
+        status,
+        enforcement: contract.enforcement,
+        metrics,
+        new: fresh,
+        existing,
+        fixed,
+        excepted: violations.filter((item) => exceptions.has(item.fingerprint)),
+        componentEdges: [...componentEdges.values()].sort((a, b) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to) || a.kind.localeCompare(b.kind)),
+        runtimeCycles: runtimeCycles.slice(0, 100),
+    }
+    return {...result, verificationHash: hash(result)}
+}
+
+export function contractForChange(contract, files = []) {
+    const normalized = rawArray(files).map(pathPrefix).filter(Boolean)
+    const components = [...new Set(normalized.map((file) => componentFor(file, contract.components)))]
+    const rules = contract.dependencyRules.filter((rule) => components.some((component) => matchSelector(rule.from, component) || matchSelector(rule.to, component)))
+    return {files: normalized, components, rules, budgets: contract.budgets, technologies: contract.technologies}
+}
+
+function rawArray(value) { return Array.isArray(value) ? value.slice(0, 200) : [] }