weavatrix 0.2.7 → 0.2.9

package/README.md

@@ -2,10 +2,11 @@
 
 **Code graph & blast-radius MCP server for AI coding agents.**
 
-Grep sees text. Weavatrix sees structure. It builds a dependency graph of any local repository —
-files, symbols, and the imports/calls/inheritance connecting them — and serves it to Claude Code,
-Codex, or any MCP client: change impact, transitive dependents, health audit, clone detection,
-coverage mapping. **36 tools available; 33 enabled by the default offline profile. Local-first: with
+Weavatrix builds and compares the living architecture of any local repository: files, symbols,
+imports, calls, inheritance, health findings, clone families and Git-history coupling. It serves that
+evidence to Claude Code, Codex, or any MCP client for change impact, transitive dependents, health
+audit, clone detection and coverage mapping. Text search is included as a convenience, not the product
+core. **38 tools available; 34 enabled by the default offline profile. Local-first: with
 the defaults, no repository data leaves your machine.**
 
 - Website: [weavatrix.com](https://weavatrix.com)
@@ -14,8 +15,8 @@ the defaults, no repository data leaves your machine.**
 
 ## Why
 
-An AI agent editing code without the dependency graph is refactoring blind. Weavatrix gives it
-answers grep can't produce:
+An AI agent editing code without architecture, health and history evidence is refactoring blind.
+Weavatrix answers questions a text index cannot:
 
 - *"What breaks if I change this?"* → `change_impact` diffs your branch (staged, unstaged and
   untracked included), maps the changed files and symbols onto the graph, and lists everything that
@@ -28,6 +29,9 @@ answers grep can't produce:
 - *"Did my refactor actually decouple anything?"* → `graph_diff base_ref=HEAD~1` builds an immutable
   baseline graph without checking it out, then reports the structural delta: new module
   dependencies, broken or introduced import cycles, and symbols that lost their last caller.
+- *"Where is the repo rotting or repeating itself?"* → `run_audit`, `find_dead_code`,
+  `find_duplicates`, `hot_path_review` and `git_history` combine deterministic findings, graph
+  connectivity and co-change evidence instead of treating a matching string as an architecture fact.
 
 - *"Is this change actually safe?"* -> `verified_change` accepts the task plus current diff/files and
   returns one proof-carrying `PASS`, `BLOCKED`, or `UNKNOWN`: compact edit contexts, exact-symbol
@@ -67,7 +71,7 @@ argument when a stricter repository boundary or a network feature is wanted:
 | `offline` (default) | Yes, only through `open_repo` | Yes, only through `trace_api_contract` | No | No |
 | `pinned` | No | No | No | No |
 | `osv` | Yes | Yes, only when called | Only when `refresh_advisories` is called | No |
-| `hosted` / `full` | Yes | Yes, only when called | Only when called | Only when `sync_graph` or `pull_architecture_contract` is called |
+| `hosted` / `full` | Yes | Yes, only when called | Only when called | `preview_sync` is local; only `sync_graph` or `pull_architecture_contract` can make a request |
 
 ```sh
 # Hard-pin one repository and expose no network tools:
@@ -125,7 +129,7 @@ confirmed by its bundled `typescript-language-server` + TypeScript runtime to `E
 `CONFLICT` means evidence disagrees. `graph_stats` reports the provenance breakdown and the semantic
 provider's `COMPLETE`, `PARTIAL`, `UNAVAILABLE`, or `OFF` state; `OFF` means precision was explicitly
 disabled and only static evidence is active. Java and Rust language-server providers are not bundled
-in 0.2.7: their edges never become `EXACT_LSP`, even when a mixed repository reports a complete
+in 0.2.9: their edges never become `EXACT_LSP`, even when a mixed repository reports a complete
 TypeScript/JavaScript overlay.
 
 The bounded JS/TS provider is enabled by default for new graphs. Set `WEAVATRIX_PRECISION=off`
@@ -133,21 +137,28 @@ before starting the MCP server for parser-only operation from the first build, o
 `precision:"off"` to `rebuild_graph` / `open_repo`. The MCPB installer exposes the same `lsp` / `off`
 choice as **TypeScript/JavaScript semantic precision**.
 
-**search / source** — `search_code` (ripgrep-backed, pure-Node fallback), `read_source` (a
+**search / source** — `search_code` (ripgrep-backed, pure-Node fallback, with repository-relative
+path globs on Windows/macOS/Linux), `read_source` (a
 symbol's actual code in one hop), `context_bundle` (definition plus grouped inbound/outbound
-containers, exact re-export sites and a few bounded source excerpts), `inspect_symbol` (one exact
+containers, exact re-export sites, call-site/target provenance and bounded excerpts around decisive
+edges), `inspect_symbol` (one exact
 bounded TS/JS reference query, logical containers, impact and source excerpts), `list_endpoints` (HTTP route inventory:
-Express/Fastify/Nest/Flask/FastAPI/Go mux/Rust axum and actix-web …)
+Express/Fastify/Nest/Flask/FastAPI/Go mux/Rust axum and actix-web, including nested Express
+`router.use(...)` mount composition, declaration/reachability counts and mount provenance),
+`trace_endpoint` (one exact composed route → handler → bounded production call graph with call-site excerpts)
 
 **health** — `find_dead_code` (bounded review queue for statically unreferenced and test-only files,
 functions, methods, and symbols, with evidence tiers, completed/remaining verification and explicit
 public/framework/dynamic caveats),
-`run_audit` (unused files/exports/dependencies with per-finding manifest/indexed-source/script/config verification,
+`run_audit` (unused files/exports/dependencies with per-finding manifest/indexed-source/script/config verification;
+`category:dependencies` isolates missing/unused/duplicate declarations, unresolved imports and lockfile drift,
 missing npm/Go/Python deps, runtime
 cycles, type-only/compile-only coupling, orphans, boundary rules, offline OSV vulnerabilities + typosquat +
 lockfile drift; accepts an immutable `base_ref`, `changed_files`, and `debt: new|existing|all` for
-review-scoped results), `find_duplicates` (MOSS winnowing over method bodies — catches copy-paste even
-after renames and can inspect strict small clones down to 12 tokens), `coverage_map` (existing coverage reports mapped onto the graph; untested hotspots
+review-scoped results; production paths are the default and `include_classified:true` opts into
+test/generated/docs evidence), `find_duplicates` (MOSS winnowing over method bodies — catches copy-paste even
+after renames and can inspect strict small clones down to 12 tokens; homogeneous router boilerplate
+is suppressed unless `include_boilerplate:true`), `coverage_map` (existing coverage reports mapped onto the graph; untested hotspots
 ranked by connectivity — tests are never executed), `hot_path_review` (bounded local-cost evidence
 with separate graph/test risk), `verify_architecture`,
 `explain_architecture_violation`, `propose_architecture_exception`
@@ -197,24 +208,78 @@ not CFG, value-propagation, or taint analysis.
 
 `query_graph` accepts optional `seed_files` when an architectural question must start from exact
 entry points. Resolved explicit seeds are exclusive by default; set `augment_seeds:true` only when
-question-derived seeds are also wanted. Broad bootstrap/tool-execution/routing questions now rank
+question-derived seeds are also wanted. A code-shaped identifier such as `startMitigate` is treated
+as a stronger bounded seed than surrounding words such as controller/service/flow; all exact
+same-name declarations are retained instead of adding unrelated concept seeds. Broad
+bootstrap/tool-execution/routing questions rank
 conventional executables and graph-declared production entry points ahead of site, documentation, benchmark
 and fixture matches. Production-first classification also applies during traversal, so unrelated
 tests/generated/docs/benchmarks do not leak back from a production seed; name a class in the
 question or set `include_classified:true` to include it. Unreferenced unmatched constant/field leaves
 are hidden unless `include_low_signal:true`. Broad ranking remains orientation evidence; use
-`seed_files` when the intended entry point is already known.
+`seed_files`, an exact endpoint, or `inspect_symbol` when the intended entry point is already known.
+Instruction words such as “REST”, “path”, and “inspect” do not become fuzzy code seeds.
 
 **advisories** *(network, explicit opt-in)* — `refresh_advisories`
 
-**hosted** *(network, explicit opt-in)* — `pull_architecture_contract`, `sync_graph`
+**hosted** *(explicit opt-in; preview is local, send/pull are networked)* — `preview_sync`,
+`pull_architecture_contract`, `sync_graph`. `preview_sync` performs no request and returns the destination,
+repository UUID, exact payload fields/sections/size/hash and a short-lived confirmation token for
+the cached payload. `sync_graph` sends only with both that token and `dry_run:false`; its legacy
+dry-run form remains a no-network compatibility alias.
 
 Quality of life: graph/health reads auto-reconcile and expose `none` / `incremental` / `full`
 freshness, with a short clean-read debounce to avoid rescanning the repository for every tool call;
 ambiguous name lookups are
 disclosed instead of silently guessed; and the server **hot-reloads its watched MCP tool entry
 modules and catalog** when those files change — other MCP helpers and analysis engines require a
-reconnect.
+reconnect. Every MCP response also carries local, transient `_meta["weavatrix/metrics"]` with elapsed
+time, output bytes/token estimate, graph freshness/revision/update and graph-cache status. These
+metrics are not persisted or transmitted by Weavatrix.
+
+### 0.2.9 correctness, signal, and consent patch
+
+- Express endpoint inventory composes nested imported `router.use(...)` mounts, so a local route such
+  as `/:attackId/startMitigate` is reported with its reachable `/warRoom/attack` prefix, declared vs
+  reachable counts and the exact static mount chain. `trace_endpoint` continues from that route into
+  the bounded call graph and call-site excerpts.
+- `context_bundle` keeps the call-site file/line separate from the target definition and adds bounded
+  excerpts around decisive edges instead of stopping inside a long leading comment.
+- `search_code` applies documented repository-relative path globs correctly when ripgrep runs on
+  Windows. Broad `query_graph` prompts no longer turn generic REST/instruction words into noisy
+  configuration-file seeds, and code-shaped identifiers outrank generic controller/service/flow
+  concepts.
+- `run_audit` is production-first by default while retaining explicit access to classified evidence;
+  `category:dependencies` provides a focused dependency-health slice;
+  duplicate review suppresses homogeneous Express router boilerplate unless requested.
+- the separate no-network `preview_sync` produces the exact payload approval artifact; `sync_graph`
+  requires that preview followed by an exact short-lived confirmation token,
+  validates the configured destination, requires HTTPS outside loopback, and never networks during
+  preview. Contract-pull HTTP failures expose actionable auth/not-found/not-ready states.
+- Every MCP call exposes transient local execution/output/freshness metrics without collection or
+  egress. The public site, privacy/security pages, package metadata and license presentation now
+  describe the same 38-tool/34-offline surface and the same network boundary.
+
+Full patch notes: [docs/releases/v0.2.9.md](docs/releases/v0.2.9.md).
+
+### 0.2.8 trust and precision patch
+
+- Dead-code review no longer labels a declaration `test-only` when it has a same-file production
+  use. Revision-bound positive evidence from an exact `inspect_symbol` point query also removes that
+  declaration from later dead-code candidates instead of remaining isolated in its cache.
+- Python dependency checks discover nested `requirements*.txt`, `requirements/*.txt`,
+  `pyproject.toml`, and `Pipfile` manifests and assign imports to their nearest manifest scope.
+  A root `test.py` is classified consistently as test code.
+- Endpoint extraction masks commented-out routes without shifting source offsets and rejects
+  primitive path-to-name maps such as `{'/.codex': 'claude'}` while retaining real route tables.
+- Rust symbols now expose concrete kinds, owner types, visibility/export state, selection ranges and
+  structural owner/member edges. This is parser evidence; Rust semantic/LSP precision remains
+  explicitly unavailable.
+- Natural-language retrieval honors explicit Rust, Python, TypeScript, JavaScript, Go, Java, and C#
+  intent in mixed repositories. Compact `verified_change` text now includes decisive exact reference
+  counts and bounded inbound caller names for every selected edit symbol.
+
+Full patch notes: [docs/releases/v0.2.8.md](docs/releases/v0.2.8.md).
 
 ### 0.2.7 verified-change workflow
 
@@ -473,20 +538,27 @@ Weavatrix itself initiates outbound HTTP only from three tools; all are absent f
 - `pull_architecture_contract` — sends the active repository's opaque stable UUID with bearer
   authentication, downloads the owner-approved target-architecture contract, validates it, and
   stores the contract in the local graph cache. It sends no source, symbol, or repository path.
-- `sync_graph` — builds a bounded evidence snapshot locally, then sends payload v3: the v2 graph
+- `preview_sync` — builds a bounded evidence snapshot locally without sending anything. The preview
+  shows the destination host/path, normalized repository name, opaque UUID,
+  payload version, exact top-level fields, included sections, node/link/byte counts and canonical
+  SHA-256 hash. A `sync_graph` call with `dry_run:false` and its exact short-lived `confirm_token` sends
+  the cached payload to the same destination. A token alone does not send while the default dry-run
+  remains active. It
+  sends payload v3: the v2 graph
   allowlist plus module dependencies, runtime/compile-time cycles, declared boundary violations,
   health findings, complexity-threshold breaches, stack identifiers, a bounded direct/transitive
   dependency graph, direct package usage, and bounded clone/divergence review candidates. Local
   analyzers may read repository source and manifests to derive those
   facts. The wire contract has no fields for file bodies, snippets, absolute host paths, environment
   values or Git remotes; unknown fields are discarded and unsafe optional path metadata is omitted.
-  The request also carries the normalized repository display name used by the
+  The confirmed request also carries the normalized repository display name used by the
   hosted list. The endpoint is **yours**, configured through `WEAVATRIX_SYNC_URL` and the optional
   `WEAVATRIX_SYNC_TOKEN`; the feature is off by default. Pass `payload_version: 2` only for an
   intentional graph-only compatibility sync—there is no silent downgrade that discards evidence.
   Graphs that predate current typed-edge/provenance metadata must be rebuilt once before V3 sync;
   V3 also refuses a stale graph so
-  source-derived evidence cannot be mixed with old topology.
+  source-derived evidence cannot be mixed with old topology. HTTPS is required except for an
+  explicitly configured loopback endpoint; embedded URL credentials and fragments are rejected.
 
 Evidence sections carry independent `state` (`COMPLETE`, `PARTIAL`, `NOT_CHECKED`,
 `NOT_APPLICABLE`, `ERROR`) and `verdict` (`PASS`, `FAIL`, `UNKNOWN`) fields plus exact
@@ -512,7 +584,7 @@ vulnerability findings. This is where each capability comes from and how it is c
 
 | Capability alert | Why it exists | Activation and boundary |
 |---|---|---|
-| Network access | `refresh_advisories` sends pinned package names and versions to OSV; `pull_architecture_contract` sends an opaque repository UUID and receives an owner-approved contract; `sync_graph` sends a normalized repository label plus an allowlisted graph/evidence payload. Evidence is derived locally from source and manifests, but source bodies, snippets, absolute paths, environment values, credentials and Git remotes are excluded | `offline` and `pinned` expose no network tools. `osv` exposes only advisory refresh. `hosted`/`full` expose all three; every request still requires an explicit tool call, and hosted calls require `WEAVATRIX_SYNC_URL` |
+| Network access | `refresh_advisories` sends pinned package names and versions to OSV; `pull_architecture_contract` sends an opaque repository UUID and receives an owner-approved contract; confirmed `sync_graph` sends a normalized repository label plus an allowlisted graph/evidence payload. Evidence is derived locally from source and manifests, but source bodies, snippets, absolute paths, environment values, credentials and Git remotes are excluded | `offline` and `pinned` expose no network tools. `osv` exposes only advisory refresh. `hosted`/`full` expose all three. Sync defaults to a no-network dry-run and then requires both `dry_run:false` and its exact short-lived token; hosted calls require `WEAVATRIX_SYNC_URL`, and non-loopback hosted endpoints require HTTPS |
 | Shell access | Local `git` powers staleness/change impact; `rg` accelerates search; the bundled TLS/tsserver process supplies bounded JS/TS semantic evidence; timed-out Windows child trees may be terminated; `verified_change` can optionally run an existing package test/check/verify script | The semantic provider never invokes repository code. Test execution separately requires `run_tests:true` plus `WEAVATRIX_ALLOW_TEST_RUNS=1`, rejects arbitrary commands and shell-sensitive arguments, and should be enabled only for trusted repository scripts |
 | Debug / dynamic loading | Cache-busted `import()` hot-reloads watched MCP tool entry modules; `createRequire` loads package metadata and parser dependencies | Loads files from the installed package; no `eval` |
 | Environment access | Reads `WEAVATRIX_*` configuration; ordinary local helpers inherit a credential-stripped environment, while TLS/tsserver receives only allowlisted OS/temp/locale values and a constrained executable path | `WEAVATRIX_SYNC_TOKEN` is removed from every child-process and worker environment. TLS/tsserver also receives no registry/proxy/cloud credentials or `NODE_OPTIONS` |
@@ -565,10 +637,10 @@ loader) behind the thin stdio entry `src/mcp-server.mjs`.
 - **Wrapper-aware API contracts** shipped in 0.2.2: persistent/ad-hoc configuration,
   conservative discovery, cross-repository handler liveness and explicit unknown states. The next
   hosted increment joins privacy-safe contract identities across separately synced services.
-- **Hosted architecture workbench** is live at
-  [app.weavatrix.com](https://app.weavatrix.com): explicit source-free sync,
-  immutable history, Flow/DSM/Map, target architecture and bounded review
-  evidence. Hosted use remains optional and owner-authenticated.
+- **Hosted architecture workbench** at
+  [app.weavatrix.com](https://app.weavatrix.com) is an access-controlled preview for
+  owner-authenticated source-free evidence and revision history. Its UI and backend evolve
+  independently from the public MCP release; local use remains fully optional.
 - **Semantic precision bridge** shipped for TypeScript/JavaScript in 0.2.4: a bounded, revision-bound
   local overlay validates references with the bundled language server while the parser graph remains
   the fallback. Java and Rust providers are not bundled yet and stay explicitly `UNAVAILABLE`.
@@ -584,4 +656,6 @@ The public alignment note for the fixed cross-product release sequence is in
 
 ## License
 
-[MIT](LICENSE) © 2026 Sergii Ziborov
+The Weavatrix source in this repository is [MIT licensed](LICENSE) © 2026 Sergii Ziborov.
+Third-party dependencies retain their own licenses. See the public
+[license page](https://weavatrix.com/license) for the same notice.

package/SECURITY.md

@@ -2,8 +2,13 @@
 
 ## Supported versions
 
-Security fixes are provided for the latest published version of Weavatrix. Upgrade to the newest
-release before reporting an issue that may already be resolved.
+| Version | Supported |
+|---|---|
+| `0.2.9.x` | Yes |
+| `0.2.8` and older | Upgrade to the latest release |
+
+Security fixes are provided for the latest published version of Weavatrix. Upgrade before reporting
+an issue that may already be resolved.
 
 ## Reporting a vulnerability
 
@@ -61,10 +66,25 @@ scripts are repository-controlled code and may have arbitrary side effects, so e
 for repositories and scripts you trust.
 
 Network capabilities are split by purpose. `osv` adds only `refresh_advisories`, which sends pinned
-package names and versions to OSV.dev when called. `hosted` / `full` also expose `sync_graph` and
-`pull_architecture_contract`; both require a user-configured endpoint, and contract pull requires
-bearer authentication. The legacy `online` capability remains an alias for advisory plus hosted
-networking so existing registrations do not break.
+package names and versions to OSV.dev when called. `hosted` / `full` also expose the local-only
+`preview_sync` plus networked `sync_graph` and `pull_architecture_contract`; the network tools require
+a user-configured endpoint, and contract pull requires bearer authentication. The legacy `online`
+capability remains an alias for advisory plus hosted networking so existing registrations do not break.
+
+`preview_sync` is the first half of a two-step consent boundary. It constructs the strict allowlisted
+payload locally but has no network path. It displays the configured hostname/path, normalized
+repository name, opaque repository UUID, payload version, included sections, node/link/byte counts
+and canonical SHA-256 hash. Sending requires `sync_graph` with both `dry_run:false` and the exact
+confirmation token for that cached payload and destination; the token
+expires after five minutes and is stored only in process memory. A token with the default dry-run,
+or an incorrect/expired token, does not send. Sync rejects
+embedded URL credentials and fragments and requires HTTPS except for explicit loopback development
+endpoints. Query parameters may be used by a configured endpoint but are not echoed in previews or
+errors.
+
+Every MCP response includes transient local `_meta["weavatrix/metrics"]` timing, output-size/token
+estimate, graph freshness/revision/update and graph-cache status. Weavatrix does not persist, aggregate
+or transmit these measurements; they are response evidence for the caller, not product telemetry.
 
 Payload v3 runs bounded local analyzers over the active repository, then sends only a strict
 graph/evidence allowlist plus a normalized repository display name. That evidence can include a
@@ -77,4 +97,7 @@ remains an explicit compatibility option and is never selected as a silent fallb
 
 `pull_architecture_contract` sends only the active repository's opaque stable UUID, receives an
 owner-approved target contract, validates it, and caches it locally. It never sends source, symbols,
-file paths, or Git metadata.
+file paths, or Git metadata. It applies the same HTTPS-outside-loopback and embedded-credential URL
+rules before sending bearer authentication. Authentication, forbidden, not-found and repository-not-ready responses
+are reported as distinct states so a missing registration or contract is not presented as an opaque
+HTTP failure.

package/docs/releases/v0.2.9.md

@@ -0,0 +1,123 @@
+# Weavatrix 0.2.9
+
+## Correctness, signal, and consent
+
+0.2.9 is a focused MCP correctness release driven by dogfooding on a 10,000-node JavaScript REST
+service. It fixes cases where broad repository orientation was useful but precision tools handed an
+agent incomplete paths, mismatched call-site provenance, or noisy review queues.
+
+## Composed Express routes
+
+`list_endpoints` now follows relative ESM/CommonJS router imports and nested `router.use(...)`
+mounts. A handler declared as `/:attackId/startMitigate` below `/warRoom` and `/attack` is reported as
+`/warRoom/attack/:attackId/startMitigate` while retaining its local declaration path. The inventory
+separates declaration and reachable-route counts, labels local versus statically composed evidence,
+and returns the exact mount files, lines and prefixes.
+
+Composition is intentionally bounded. Dynamic mount expressions that cannot be resolved statically
+remain local-path evidence rather than guessed full routes.
+
+The new `trace_endpoint` tool resolves one exact composed route, binds its handler without silently
+choosing among same-name symbols, and traverses a bounded production-only call graph with excerpts at
+the actual edge lines. On the dogfood route it recovered router mount provenance, controller:268,
+service, messaging and task calls in one graph-anchored response.
+
+## Edge-centered source context
+
+`context_bundle` now keeps two facts separate:
+
+- the file and line containing an outbound call;
+- the target symbol's definition file.
+
+The compact source bundle prioritizes the definition and bounded excerpts around decisive inbound and
+outbound edge lines. Long Swagger/JSDoc comments at the beginning of a controller therefore no longer
+consume the only excerpt before the real service call.
+
+## Search and retrieval signal
+
+- Ripgrep-backed `search_code` runs from the repository root, so documented relative globs such as
+  `services/attack/**` behave consistently on Windows, macOS, and Linux.
+- Broad `query_graph` prompts discard generic REST/instruction terms before fuzzy seeding and use a
+  smaller automatic seed set. When prose contains a code-shaped identifier such as `startMitigate`,
+  its exact same-name declarations are exclusive automatic seeds; generic controller/service/flow
+  words cannot add unrelated modules. Exact files, endpoints, and symbols remain the preferred
+  precision path.
+
+## Production-first review queues
+
+- `run_audit` suppresses findings whose evidence is entirely in tests, generated output, docs,
+  benchmarks, fixtures, mocks, or stories. `include_classified:true` restores the full diagnostic
+  view; mixed production/non-production evidence remains visible by default.
+- `run_audit category=dependencies` projects missing, unused and duplicate declarations, unresolved
+  imports and lockfile drift into one dependency-health review without relabelling their native
+  deterministic finding identities.
+- `find_duplicates` suppresses groups made entirely of router boilerplate by default.
+  `include_boilerplate:true` restores them for framework-template review.
+- Incomplete OSV coverage remains explicit as `NOT_CHECKED`; this release does not turn missing
+  advisory data into a clean security verdict.
+
+## Preview-confirm graph sync
+
+`preview_sync` and `sync_graph` are now a two-step consent flow:
+
+1. `preview_sync` builds and validates the strict payload allowlist locally and has no network path.
+2. Display the destination, repository identity, exact top-level fields, payload
+   version/sections/size/hash and return a short-lived confirmation token.
+3. `sync_graph` sends only the exact cached payload when it supplies both `dry_run:false` and that token
+   within five minutes. A token alone remains a no-network dry-run.
+
+Incorrect or expired tokens never send. Sync also rejects embedded URL credentials/fragments and
+requires HTTPS except for loopback development endpoints. URL query values are not echoed in previews
+or errors.
+
+`pull_architecture_contract` applies the same HTTPS-outside-loopback and embedded-credential URL
+rules before sending bearer authentication. It now distinguishes authentication, forbidden,
+repository-not-registered, endpoint-not-found, repository-not-ready and general HTTP failures.
+Hosted's `REPOSITORY_NOT_FOUND` response is therefore no longer confused with a wrong endpoint;
+`NOT_CONFIGURED` explicitly means sync/authentication succeeded but no target contract was saved.
+
+## Per-call metrics without telemetry
+
+Every MCP response carries transient local `_meta["weavatrix/metrics"]`: duration, text/structured
+bytes, estimated output tokens, graph freshness/revision/update and graph-cache status. These values
+are returned to the caller only; Weavatrix does not persist, aggregate or transmit them.
+
+## Public contract alignment
+
+The README, package manifests, public home page, privacy policy, security policy, and new public
+license/security pages now describe the same 38-tool surface, 34-tool offline default, preview-confirm
+sync behavior, and source/data boundary. The optional Hosted workbench is described as an
+independently evolving access-controlled preview. Payload v3 is unchanged, so existing Hosted storage,
+history and evidence readers remain wire-compatible; Hosted contract tests validate v1/v2/v3.
+
+## Compatibility
+
+The release adds `trace_endpoint` to the local source surface and `preview_sync` to the explicit
+Hosted surface, taking the catalog from 36 to 38 tools and the default offline profile from 33 to 34.
+Existing offline, pinned, osv, hosted, full and legacy online capability names remain valid.
+`sync_graph` retains its no-network dry-run compatibility form, but `preview_sync` is the canonical
+approval step for new clients.
+
+## Verification
+
+- Full Node suite: 502 tests, 499 passed, 3 platform skips, 0 failed.
+- Deterministic six-language, cross-repository, framework-convention and MCP lifecycle benchmark:
+  `PASS`.
+- Real pinned corpus: 6 of 6 repositories `PASS` across TypeScript, JavaScript, Python, Go, Java and
+  Rust.
+- Release metadata consistency: `PASS`; production npm audit: 0 vulnerabilities; npm 0.2.9 package
+  dry-run: 154 files, 413,993 bytes.
+- Portable MCPB: manifest validation `PASS`; archive built at 6.7 MiB
+  (`5a5def22491bc0777c882c314b12be7153d56d29`). The local archive is unsigned.
+- Direct `controller-rest-api` dogfood: 1,076 indexed files and 989 reachable composed endpoints;
+  public and internal composed
+  `startMitigate` routes found; documented attack glob returned real matches; context preserved
+  `controller:268 → service` with the call excerpt; production-first audit retained the manually
+  confirmed missing `mongodb` declaration and explicit `OSV NOT_CHECKED`; 2 router-only clone groups
+  were separated from 60 default groups; exact identifier seeding returned only controller, service
+  and messaging declarations.
+
+Focused regressions cover nested Express mounts, call-site/target provenance and edge excerpts,
+Windows path globs, generic REST and exact-identifier seed handling, production-first audit filtering,
+router boilerplate suppression, no-network sync previews, confirmation-token mismatch, URL redaction,
+and actionable contract 404 state.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "weavatrix",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "type": "module",
-  "description": "Weavatrix — code graph & blast-radius MCP server for AI coding agents: change impact, transitive dependents, health audit, duplicate detection, and coverage mapping over any local repository.",
+  "description": "Weavatrix — architecture graph, health, clone and history MCP server for AI coding agents: blast radius, dependency audit, graph diff and coverage over any local repository.",
   "author": "Sergii Ziborov <sergii.ziborov@gmail.com>",
   "license": "MIT",
   "homepage": "https://weavatrix.com",
@@ -26,7 +26,7 @@
     "skill",
     "scripts/run-agent-task-benchmark.mjs",
     "docs/agent-task-benchmark.md",
-    "docs/releases/v0.2.7.md",
+    "docs/releases/v0.2.9.md",
     "README.md",
     "SECURITY.md",
     "LICENSE"

package/skill/SKILL.md

@@ -16,7 +16,7 @@ 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 `refresh_advisories`, `pull_architecture_contract`, or `sync_graph` is missing, do not diagnose a
+If `refresh_advisories`, `preview_sync`, `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:
@@ -24,7 +24,7 @@ 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`.
+- `hosted` / `full`: `osv` plus local-only `preview_sync`, `pull_architecture_contract` and `sync_graph`.
 
 The legacy `online` capability remains a compatibility alias for `advisories,hosted`; prefer the
 named profiles for new registrations.
@@ -117,8 +117,8 @@ Start from the task, not from the complete tool list:
   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
+  package names + versions so `run_audit` has fresh vulnerability data) and `sync_graph` (pushes only
+  the exact allowlisted graph/evidence contract previously serialized by local-only `preview_sync` 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
@@ -175,7 +175,9 @@ Start from the task, not from the complete tool list:
   `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).
+- **API inventory**: `list_endpoints` (including mount provenance, Next.js App Router, Rust axum and
+  actix-web). When one exact route is known, use `trace_endpoint` for its composed mount chain,
+  handler and bounded production call graph instead of broad natural-language traversal.
 - **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`. `path` may be a segment-aligned fragment (`/query` can select
@@ -237,7 +239,10 @@ visible. `managedDependencies` documents modules provided outside the repo's Pyt
 
 ## Sync
 
-`sync_graph` defaults to payload v3: graph metadata plus deterministic architecture, health, stack,
+Call `preview_sync` first. It validates the configured destination and serializes payload v3 locally,
+returning the repository UUID, exact fields/sections, counts, bytes, hash and short-lived confirmation
+token without networking. After explicit approval, call `sync_graph dry_run=false` with that token.
+Payload v3 contains 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
@@ -257,7 +262,7 @@ the working tree, must be rebuilt first. Sync remains unavailable until the user
 - `refresh_advisories` is unavailable → with the user's approval, re-register/reconfigure the MCP
   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
+- `preview_sync` / `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`,

package/src/analysis/dead-check.js

@@ -126,14 +126,29 @@ export function computeDead(graph, sources, { entrySet = new Set() } = {}) {
 
   const symbolNames = new Set([...symById.values()].map((node) => bareName(node.label)).filter(Boolean));
   const occurrenceFiles = new Map();
+  const occurrenceCounts = new Map();
   for (const [file, text] of sources) for (const match of String(text || "").matchAll(IDENT_RE)) {
     const name = match[0];
     if (!symbolNames.has(name)) continue;
     const files = occurrenceFiles.get(name) || new Set();
     files.add(file);
     occurrenceFiles.set(name, files);
+    const counts = occurrenceCounts.get(name) || new Map();
+    counts.set(file, (counts.get(file) || 0) + 1);
+    occurrenceCounts.set(name, counts);
   }
 
+  const declarationCounts = new Map();
+  for (const node of symById.values()) {
+    const name = bareName(node.label);
+    if (!name) continue;
+    const key = `${node.source_file}\0${name}`;
+    declarationCounts.set(key, (declarationCounts.get(key) || 0) + 1);
+  }
+  const exactReferenceIds = new Set(graph.precisionReferenceSymbols || []);
+  const exactProductionReferenceIds = new Set(graph.precisionProductionReferenceSymbols || []);
+  const exactTestReferenceIds = new Set(graph.precisionTestReferenceSymbols || []);
+
   // decorated defs (@app.route/@app.event/@pytest.fixture…) are entered by the framework: trust the
   // builder's flag when present, else walk the source line(s) above the definition (graph-builder graphs).
   const lineCache = new Map();
@@ -155,6 +170,7 @@ export function computeDead(graph, sources, { entrySet = new Set() } = {}) {
 
   const isReferenced = (n) => {
     if (inbound.has(n.id)) return true;                          // a real graph edge targets it
+    if (exactReferenceIds.has(String(n.id))) return true;        // revision-bound point-query evidence found a caller
     const name = bareName(n.label);
     if (!name || !/^[A-Za-z_$]/.test(name)) return true;         // selectors/odd labels → don't flag
     if (/^__\w+__$/.test(name)) return true;                     // dunders are invoked implicitly (with/str/==/iter…), never spelled
@@ -182,8 +198,14 @@ export function computeDead(graph, sources, { entrySet = new Set() } = {}) {
     const name = bareName(n.label);
     const occurrenceSet = occurrenceFiles.get(name) || new Set();
     const externalOccurrences = [...occurrenceSet].filter((file) => file !== n.source_file);
+    const localOccurrences = occurrenceCounts.get(name)?.get(n.source_file) || 0;
+    const localDeclarations = declarationCounts.get(`${n.source_file}\0${name}`) || 0;
+    const hasLocalProductionUse = localOccurrences > localDeclarations;
     const lexicalTestOnly = externalOccurrences.length > 0 && externalOccurrences.every((file) => isTestFile(file));
-    if (hasProductionInbound || (!hasTestInbound && !lexicalTestOnly)) continue;
+    const hasExactProductionInbound = exactProductionReferenceIds.has(String(n.id));
+    const hasExactTestInbound = exactTestReferenceIds.has(String(n.id));
+    if (hasProductionInbound || hasExactProductionInbound || hasLocalProductionUse
+      || (!hasTestInbound && !hasExactTestInbound && !lexicalTestOnly)) continue;
     testOnlySymbols.push({
       id: n.id,
       file: n.source_file,
@@ -191,7 +213,7 @@ export function computeDead(graph, sources, { entrySet = new Set() } = {}) {
       test: false,
       reason: "referenced only from test/e2e code; no production consumer was found",
       testConsumerFiles: [...new Set(sourceFiles.filter((file) => file && isTestFile(file)))].sort(),
-      evidence: hasTestInbound ? "graph" : "lexical",
+      evidence: hasTestInbound ? "graph" : hasExactTestInbound ? "exact-semantic" : "lexical",
       publicApi: n.exported === true || ["public", "protected"].includes(String(n.visibility || "").toLowerCase()),
     });
   }

package/src/analysis/dep-check-ecosystems.js

@@ -1,6 +1,6 @@
 import { makeFinding } from "./findings.js";
 
-const TEST_PATH_RE = /(^|[/\\])(test|tests|__tests__|spec|e2e|__mocks__)([/\\]|$)|[._-](test|spec)\.[a-z0-9]+$|_test\.go$/i;
+const TEST_PATH_RE = /(^|[/\\])(test|tests|__tests__|spec|e2e|__mocks__)([/\\]|$)|[._-](test|spec)\.[a-z0-9]+$|_test\.go$|(^|[/\\])test(?:_[^/\\]*)?\.py$/i;
 const escRe = (s) => String(s).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 const mentioned = (blob, name) => new RegExp(`(^|[^\\w@.-])${escRe(name)}($|[^\\w.-])`).test(blob);
 
@@ -79,7 +79,7 @@ const PY_TOOL_DISTS = new Set(("pytest tox nox black ruff flake8 pylint mypy pyr
   "pip-tools uv virtualenv pipenv gunicorn uwsgi supervisor ipython jupyter jupyterlab notebook ipykernel codecov autopep8 yapf commitizen detect-secrets safety pip-audit hatchling flit flit-core pdm").split(" "));
 const pyNorm = (n) => String(n || "").toLowerCase().replace(/[-_.]+/g, "-");
 
-export function computePyDepFindings({
+function computePyDepFindingsFlat({
   externalImports = [], pyManifest = null, configTexts = new Map(),
   managedDependencies = [], ignoredDependencies = [], nonRuntimeRoots = [],
 } = {}) {
@@ -161,3 +161,42 @@ export function computePyDepFindings({
   }
   return { findings, declared, managed };
 }
+
+const normPyScope = (root) => String(root || "").replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+|\/+$/g, "");
+const pyScopeOwns = (root, file) => !root || file === root || String(file || "").replace(/\\/g, "/").startsWith(`${root}/`);
+
+export function computePyDepFindings(options = {}) {
+  const scopes = Array.isArray(options.pyManifest?.scopes) ? options.pyManifest.scopes : [];
+  if (!scopes.length) return computePyDepFindingsFlat(options);
+  const normalized = scopes.map((scope) => ({ ...scope, root: normPyScope(scope.root) }))
+    .sort((left, right) => right.root.length - left.root.length);
+  if (!normalized.some((scope) => !scope.root)) normalized.push({ root: "", present: false, deps: [], manifests: [] });
+  const importsByScope = new Map(normalized.map((scope) => [scope, []]));
+  const configByScope = new Map(normalized.map((scope) => [scope, new Map()]));
+  for (const entry of options.externalImports || []) {
+    const owner = normalized.find((scope) => pyScopeOwns(scope.root, entry.file)) || normalized.at(-1);
+    importsByScope.get(owner).push(entry);
+  }
+  for (const [file, text] of options.configTexts || new Map()) {
+    const owner = normalized.find((scope) => pyScopeOwns(scope.root, file)) || normalized.at(-1);
+    configByScope.get(owner).set(file, text);
+  }
+  const findings = [];
+  const declared = new Set();
+  const managed = new Set();
+  for (const scope of normalized) {
+    const result = computePyDepFindingsFlat({
+      ...options,
+      externalImports: importsByScope.get(scope),
+      configTexts: configByScope.get(scope),
+      pyManifest: {present: scope.present, deps: scope.deps || []},
+    });
+    findings.push(...result.findings.map((finding) => ({
+      ...finding,
+      ...(scope.manifests?.length ? {manifest: scope.manifests[0]} : {}),
+    })));
+    for (const name of result.declared) declared.add(`${scope.root || "."}:${name}`);
+    for (const name of result.managed) managed.add(name);
+  }
+  return { findings, declared, managed };
+}