weavatrix 0.3.14 → 1.0.0

package/LICENSE

@@ -19,3 +19,4 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+

package/README.md

@@ -1,233 +1,265 @@
 # Weavatrix
 
-**Local repository intelligence for AI coding agents — understand an application fast, then change it with evidence.**
+[![CI](https://github.com/sergii-ziborov/weavatrix/actions/workflows/ci.yml/badge.svg)](https://github.com/sergii-ziborov/weavatrix/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/weavatrix.svg)](https://www.npmjs.com/package/weavatrix)
+[![crates.io](https://img.shields.io/crates/v/weavatrix-rust.svg)](https://crates.io/crates/weavatrix-rust)
+[![docs.rs](https://docs.rs/weavatrix-rust/badge.svg)](https://docs.rs/weavatrix-rust)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/sergii-ziborov/weavatrix/blob/main/LICENSE)
+
+**Give your coding agent the map of the repository before it starts guessing.**
+
+Weavatrix is a native Rust repository-intelligence engine and MCP server for
+Codex, Claude Code, and other coding agents. It turns source, Git history,
+coverage, endpoints, infrastructure, clones, search, vectors, semantic links,
+and temporal memory into one always-fresh evidence graph.
+
+Ask what breaks, where an API is used, why a cycle exists, which code is truly
+dead, or whether a change preserved the architecture. Weavatrix answers from
+bounded graph evidence with file, line, extractor, confidence, and revision
+provenance—not from a wider grep and not from a fabricated certainty score.
+
+| Release proof | Result |
+| --- | ---: |
+| Read-only MCP tools | **39** |
+| Installed-package cold speed vs `weavatrix-js` | **30.34x** |
+| Warm tool-call speed vs `weavatrix-js` | **156.10x** |
+| Shared JS call targets missing or wrong | **0 / 0** |
+| Shared imports, methods, and re-exports covered | **100%** |
+| Rust line coverage release gate | **87.18%** |
+| Runtime downloads, install scripts, external executables | **0** |
+
+## Install in 30 seconds
 
-Weavatrix builds a reusable living graph of any local repository — files, symbols, imports, calls,
-inheritance, Health findings, clone families and Git-history coupling — and gives Claude Code, Codex
-or any MCP client a bounded map for fast understanding and low repeated context. The same graph then
-answers change impact, Health, dead-code review, duplicates, history and intended-architecture
-questions. **34 network-free tools. No repository data leaves your machine.**
-
-- Website: [weavatrix.com](https://weavatrix.com)
-- Source: [github.com/sergii-ziborov/weavatrix](https://github.com/sergii-ziborov/weavatrix)
-- npm: [`weavatrix`](https://www.npmjs.com/package/weavatrix) — `npx -y weavatrix <repoRoot>`
-
-This package is the complete offline engine under the MIT license: it reads and analyzes your code,
-initiates no outbound HTTP, and never edits your source. It is the read-only base of a layered stack —
-add [`weavatrix-refactor`](https://github.com/sergii-ziborov/weavatrix-refactor) (Apache-2.0) to apply
-hash-verified, reversible edits, or [`weavatrix-online`](https://github.com/sergii-ziborov/weavatrix-online)
-for authorized Cloud or self-hosted sync. Each is an optional superset that depends on this core through
-a supported extension API; the offline/online split is documented in
-[docs/adr/0001-v0.3-offline-online-split.md](docs/adr/0001-v0.3-offline-online-split.md).
-
-## Install
+```sh
+npx -y weavatrix mcp .
+```
 
-Requires Node ≥ 18.
+Or install the Rust binary directly:
 
 ```sh
-# Claude Code
-claude mcp add -s user weavatrix -- npx -y weavatrix <repoRoot>
-
-# Codex CLI
-codex mcp add weavatrix -- npx -y weavatrix <repoRoot>
+cargo install weavatrix-rust
+weavatrix mcp . --profile=all
 ```
 
+### Codex
+
 ```toml
-# or in ~/.codex/config.toml
+# ~/.codex/config.toml
 [mcp_servers.weavatrix]
 command = "npx"
-args = ["-y", "weavatrix", "C:/path/to/repo"]
-startup_timeout_sec = 20
-tool_timeout_sec = 60
+args = ["-y", "weavatrix", "mcp", "."]
 ```
 
-Or run from a clone:
+### Claude Code
 
 ```sh
-git clone https://github.com/sergii-ziborov/weavatrix
-cd weavatrix && npm install
-claude mcp add -s user weavatrix -- node <path-to>/weavatrix/bin/weavatrix-mcp.mjs <repoRoot>
+claude mcp add weavatrix -- npx -y weavatrix mcp .
 ```
 
-`<repoRoot>` is the repository to start with. Graphs are derived data and never live in your repo:
-they are stored in the per-user registry at `~/.weavatrix/graphs/<repository-storage-key>/graph.json`
-(with a stable `.repository-id` beside them). No graph yet? Ask the agent to call `rebuild_graph`, or
-just use a tool — graph and Health reads auto-reconcile the working graph before answering.
+The npm package contains prebuilt binaries for Windows x64/arm64, macOS
+x64/arm64, and glibc-based Linux x64/arm64. It has no install script and does
+not download a binary after installation.
+
+## What your agent can ask
+
+```text
+What breaks if I change src/auth/middleware.ts?
+Trace POST /api/orders through the backend and its clients.
+Which production symbols are dead, and what evidence says so?
+Show duplicate implementations but suppress router boilerplate.
+Which service violates the intended architecture, and why?
+Find every HTTP, GraphQL, gRPC, Kafka, RabbitMQ, NATS, JMS,
+SQS or SNS contract affected by this branch.
+Build the smallest context bundle needed to edit this symbol safely.
+Suggest internal links between these pages without mixing inferred SEO
+relationships into the deterministic code graph.
+```
 
-An agent skill with recipes ships in [skill/SKILL.md](skill/SKILL.md) — install it as
-`~/.claude/skills/weavatrix/SKILL.md` (Claude Code) or `~/.codex/skills/weavatrix/SKILL.md` (Codex).
+Weavatrix builds the graph once and projects the same revision into small,
+task-specific answers. A health result, endpoint trace, blast radius, clone
+family, architecture violation, and context bundle therefore agree about
+repository identity and evidence.
 
-## Configure
+## The 39-tool surface
 
-**Security profile** — pass a profile as the final positional argument (omitted = `offline`):
+| Workflow | Tools |
+| --- | --- |
+| Graph orientation | `graph_stats`, `get_node`, `get_neighbors`, `query_graph`, `god_nodes`, `shortest_path`, `get_community`, `list_communities`, `module_map` |
+| Change impact and proof | `get_dependents`, `change_impact`, `verified_change`, `prepare_change`, `graph_diff` |
+| Exact source context | `search_code`, `read_source`, `inspect_symbol`, `context_bundle` |
+| Health and quality | `find_duplicates`, `find_dead_code`, `run_audit`, `coverage_map`, `hot_path_review` |
+| APIs and transports | `list_endpoints`, `trace_endpoint`, `trace_api_contract` |
+| Architecture | `get_architecture_contract`, `verify_architecture`, `explain_architecture_violation`, `propose_architecture_exception` |
+| Git and repositories | `git_history`, `cross_repo_git`, `open_repo`, `list_known_repos`, `rebuild_graph` |
+| Native Rust extensions | `vector_search`, `semantic_link`, `seo_link_suggestions`, `memory_context` |
 
-| Profile | Local repository switching | Cross-repo graph reads | Network requests | Tools |
-|---|---:|---:|---:|---:|
-| `offline` (default) | Yes, only via `open_repo` | Yes, only via `trace_api_contract` | None | 34 |
-| `pinned` | No | No | None | 31 |
+Three profiles expose bounded views of the same read-only engine:
 
 ```sh
-# hard-pin one repository and expose no cross-repo tools:
-claude mcp add -s user weavatrix -- npx -y weavatrix <repoRoot> pinned
+weavatrix mcp . --profile=all   # all 39 tools
+weavatrix mcp . --profile=code  # code and architecture
+weavatrix mcp . --profile=seo   # content and semantic linking
 ```
 
-Advanced registrations may pass an exact comma-separated capability set instead:
-`graph,search,source,health,build,retarget,crossrepo`. A custom list must include `crossrepo` to
-expose `trace_api_contract`. Legacy `online`/`osv`/`hosted`/`full` names fail loudly and point to
-`weavatrix-online`.
-
-**Semantic precision** — a bounded, read-only TypeScript/JavaScript language-server overlay is on by
-default for new graphs and upgrades confirmed references to `EXACT_LSP`. Turn it off for parser-only
-operation with `WEAVATRIX_PRECISION=off` (env), `precision:"off"` on `rebuild_graph`/`open_repo`, or
-the MCPB installer's precision choice. Java and Rust have no bundled language server; their edges stay
-parser-derived.
-
-The startup prewarm queries 32 ranked symbols (never more than 64) by default. For a deliberate
-high-budget pass, set `WEAVATRIX_PRECISION_MAX_SYMBOLS` above 64 or `WEAVATRIX_PRECISION_PREWARM=full`
-to cover every eligible target up to a 10,000-symbol ceiling; `WEAVATRIX_PRECISION_MAX_REFERENCES`,
-`WEAVATRIX_PRECISION_MAX_LINKS` and `WEAVATRIX_PRECISION_TIMEOUT_MS` tune the budgets. Repositories
-that exceed a hard ceiling stay honestly `PARTIAL`.
-
-**Repository config files** (all optional, repository-root):
-
-- `.weavatrixignore` — analysis-only exclusions that should stay tracked in Git (`*`, `**`, `?`,
-  root-anchored `/patterns`, directory suffixes, ordered `!` re-includes).
-- `.weavatrix.json` — cross-repository HTTP client/wrapper contracts (`httpContracts`) and
-  `classify.product` overrides.
-- `.weavatrix-deps.json` — `entrypoints`, `nonRuntimeRoots`, and Python `managedDependencies` /
-  `ignoreDependencies` for conventions that cannot be inferred safely.
-
-**Test execution** — `verified_change` is read-only by default. Running an existing package
-test/check/verify script requires both `run_tests:true` and `WEAVATRIX_ALLOW_TEST_RUNS=1`; arbitrary
-commands are always rejected.
-
-After an upgrade, reconnect the MCP server or start a new agent task before checking the tool list —
-many clients snapshot `tools/list` for the lifetime of a connection. `graph_stats` reports the running
-version, enabled capabilities and registered-tool count so a cached process is distinguishable from
-the installed package.
-
-## Tools
-
-The 34 methods project the same reusable graph into the smallest view a task needs.
-
-- **graph** — `graph_stats`, `get_node`, `get_neighbors`, `query_graph`, `god_nodes`, `shortest_path`,
-  `get_community`, `list_communities`, `module_map`, `get_dependents`, `change_impact`,
-  `verified_change`, `git_history`, `graph_diff`, `get_architecture_contract`, `prepare_change`.
-  Runtime, TypeScript type-only and language compile-only edges are reported separately; every edge
-  carries versioned provenance (`EXTRACTED` / `RESOLVED` / `INFERRED`, upgraded to `EXACT_LSP` only by
-  the bundled TS/JS overlay, `CONFLICT` when evidence disagrees).
-- **search / source** — `search_code` (ripgrep-backed with a pure-Node fallback and
-  repository-relative path globs), `read_source`, `context_bundle`, `inspect_symbol`,
-  `list_endpoints` (Express/Fastify/Nest/Flask/FastAPI/Go mux/Rust axum & actix-web/Spring),
-  `trace_endpoint`.
-- **health** — `find_dead_code`, `run_audit` (capability matrix + unused files/exports/dependencies,
-  missing/duplicate deps, offline OSV vulnerabilities, typosquats, lockfile drift; `base_ref` +
-  `debt: new|existing|all` for review-scoped results), `find_duplicates` (MOSS winnowing, catches
-  renamed clones), `coverage_map`, `hot_path_review`, `verify_architecture`,
-  `explain_architecture_violation`, `propose_architecture_exception`.
-- **build** — `rebuild_graph` (reports the structural delta, keeps the prior state as `graph.prev.json`).
-- **retarget** *(in `offline`, absent from `pinned`)* — `open_repo`, `list_known_repos`.
-- **crossrepo** *(in `offline`, absent from `pinned`)* — `trace_api_contract` (joins routes to client
-  call-sites across registered local graphs; reads no source). Results are compact and paginated by
-  default (`page_size`, opaque `cursor`, and bounded `per_item_limit` samples); `response_detail="full"`
-  is an explicit opt-in and remains paginated.
-
-Every finding is review evidence, never an auto-delete verdict: `find_dead_code` /
-`run_audit category=unused` always return `REVIEW_REQUIRED` with `autoDelete:false`. Typecheck, tests
-and runtime checks remain the release authority.
-
-## Always-fresh graph
-
-There is no watcher daemon to run and no manual refresh step: every graph/health call reconciles the
-graph before answering. A Git-token freshness probe (HEAD + dirty/untracked content, debounced 2 s)
-decides whether anything changed; when it did, a bounded incremental refresh reparses only the changed
-files plus their reverse importers (≤ 24 changed / ≤ 80 reparsed JS/TS files) and merges the scoped
-result into the previous graph under a file lock. Config/lockfile edits, export-surface changes,
-barrel files and non-JS/TS languages fall back to a full rebuild — correctness always wins over speed.
-Each refreshed answer carries a structured `refresh` record (`none` / `incremental` / `full`, changed
-file count), so an agent can tell exactly which repository state it is reasoning about. The same
-guarantees hold across concurrent MCP clients sharing one canonical graph.
-
-## Benchmarks
-
-Two gates ship in the repository:
-
-- `npm run benchmark` — a reproducible golden suite for TypeScript, JavaScript, Python, Go, Java and
-  Rust, plus cross-repository HTTP matching, framework conventions and the MCP graph lifecycle.
-- `npm run benchmark:real` — compares revision-pinned local snapshots against the checked-in 0.2.1
-  relation baseline; it fails on unexplained signal loss (`MISSING`/`STALE`/`UNBASELINED` stay
-  incomplete, not green).
-
-Representative local regression run (Windows x64, Node 24.15.0):
-
-| Gate | Result | Selected evidence |
-|---|---:|---|
-| Six language fixtures | 6/6 PASS | exact symbols/edges and complete edge provenance |
-| Cross-repo fixture | PASS, ~432 ms cold | endpoint match, typed wrapper, external use |
-| Lifecycle | PASS | `full → incremental → none → reconnect/none` |
-| Total fixture cold build | ~1.31 s | all six language graphs |
-| Real-repository baseline | 6/6 PASS | TS, JS, Python, Go, Java and Rust snapshots |
-
-Real snapshots ranged from 473 nodes / 1,165 edges in 0.22 s (Go) to 8,192 nodes / 21,814 edges in
-9.44 s (TypeScript). These are regression measurements on one machine, not competitor benchmarks. See
-[benchmark/cases.mjs](benchmark/cases.mjs) and [docs/benchmarking.md](docs/benchmarking.md).
-
-## Security model
-
-Socket capability alerts describe the expected powers of a local code-analysis tool; they are not
-vulnerability findings. Where each comes from and how it is bounded:
-
-| Capability alert | Why it exists | Activation and boundary |
-|---|---|---|
-| Network access | None in the MIT core | `offline`/`pinned` expose only local tools; online integration is a separate package |
-| Shell access | Local `git` (staleness/impact), `rg` (search), the bundled tsserver for JS/TS semantics, Windows child-tree termination, optional `verified_change` test scripts | The semantic provider never runs repository code; test execution needs `run_tests:true` + `WEAVATRIX_ALLOW_TEST_RUNS=1` and rejects arbitrary commands |
-| Debug / dynamic loading | Cache-busted `import()` hot-reloads watched MCP tool modules; `createRequire` loads package metadata and parser deps | Loads files from the installed package only; no `eval` |
-| Environment access | Reads local `WEAVATRIX_*` settings; children inherit a credential-stripped env | Connector secrets are removed; tsserver receives only allowlisted OS/temp/locale values |
-| Filesystem access | Reads the active repository, graph, lockfiles and coverage; writes derived graphs and caches | Realpath containment blocks traversal and symlink escapes; `pinned` removes `open_repo` |
-| URL strings | Advisory findings may contain fixed OSV documentation links | The core has no outbound request implementation |
-
-`read_source` accepts repo-relative regular files only, caps a read at 2 MB, and refuses lexical or
-realpath escapes. Report suspected vulnerabilities privately as described in [SECURITY.md](SECURITY.md).
-
-## Languages
-
-JavaScript · TypeScript · TSX · Python · Go · Java · C# · Rust · Solidity · HTML · CSS — parsed with
-[web-tree-sitter](https://github.com/tree-sitter/tree-sitter) WASM grammars; no Python install and no
-native compilation.
-
-SQL is indexed without a grammar: `.sql` files contribute tables, views, columns, functions, indexes
-and triggers as first-class graph symbols, and SQL found in string literals of any other language
-links the enclosing function to the table it queries. That makes schema objects visible to
-`change_impact`/`get_dependents` (who touches this table?) and lets the dead-code check flag columns
-no statement references — conservatively: verdicts require literal-SQL evidence in the repo, and
-`SELECT *`-consumed tables never have their columns judged by name (ORM-generated SQL stays invisible
-and is therefore never judged either).
-
-Test surfaces are classified per file (path conventions plus `.weavatrix.json` overrides) and, for
-Rust, per symbol: `#[cfg(test)]` modules and `#[test]`/`#[bench]` items inside production `.rs` files
-carry a node-level `test_surface` flag, so dead-code, query, hot-path and hub tools treat them as
-tests rather than production code.
-
-## Development
+Optional Cargo features remove capabilities from `tools/list`; disabled
+features are never advertised as unavailable stubs.
+
+## More than a code graph
+
+### Languages and repository surfaces
+
+- Rust AST extraction plus JavaScript, TypeScript, Python, Go, Java, C#, C,
+  C++, Bash, SQL, Solidity, Swift, HTML, CSS-family, Terraform, XML,
+  Markdown-family, GraphQL, Protobuf, YAML, and Kubernetes structures;
+- HTTP routes, GraphQL operations, gRPC services and streaming modes;
+- Kafka, RabbitMQ/AMQP, JMS, NATS, SQS, SNS, and MongoDB evidence;
+- package manifests, lockfiles, JSON configuration, architecture contracts,
+  and measured coverage artifacts.
+
+### Lossless parsing
+
+The first-party
+[`weavatrix-parse`](https://github.com/sergii-ziborov/weavatrix-parse)
+tokenizer preserves every input byte. Structural extraction is fast, but the
+original source remains recoverable for diagnostics, exact spans, future
+compiler work, and source-to-source transformations.
+
+The parser is not a regex fallback hidden behind a Rust binary. Its release
+suite checks byte-for-byte round trips, exact facts, GraphQL/Protobuf fixtures,
+and import agreement against tree-sitter on real repositories.
+
+### Direct Git and local-only operation
+
+Weavatrix reads Git objects through
+[`weavatrix-git`](https://github.com/sergii-ziborov/weavatrix-git); it does not
+spawn `git`. Search does not spawn `rg`. The MCP server does not launch Node,
+Python, a language server, or code from the analyzed repository.
+
+Production code has no network or source-write path. Derived in-memory state
+can refresh after files change, but Weavatrix does not edit application source
+or create commits.
+
+### Evidence instead of overclaiming
+
+Every relationship records its extractor, evidence class, confidence, and
+optional source span. Static reachability is never reported as measured test
+coverage. Dynamic or ambiguous JavaScript and Python behavior remains bounded
+evidence for the agent instead of being silently connected to a same-named
+symbol.
+
+## Speed measured at the package boundary
+
+The release benchmark does not compare a Rust library function with a full
+JavaScript process. It packs and installs both npm packages into isolated
+roots, starts fresh MCP processes with empty caches, validates package and
+protocol identity, calls the same tools, and checks clean shutdown.
+
+On 2026-07-29, `weavatrix` 1.0.0 with Rust engine 1.0.1 was compared with
+`weavatrix-js` 0.3.15 using three paired fresh processes per tool and five warm
+calls per process:
+
+| Tool | Rust cold median | JavaScript cold median | Speedup |
+| --- | ---: | ---: | ---: |
+| `graph_stats` | 249.87 ms | 7,561.94 ms | **30.73x** |
+| `list_endpoints` | 321.07 ms | 7,400.17 ms | **26.15x** |
+| `find_dead_code` | 310.45 ms | 9,298.27 ms | **31.81x** |
+| `run_audit` | 378.47 ms | 11,583.83 ms | **35.62x** |
+
+The median of all 12 paired cold ratios is **30.34x**. Warm-call medians are
+3.17 ms for Rust and 494.83 ms for JavaScript, a **156.10x** speedup. Every
+selected tool was faster; the gate requires at least 24x cold overall, at
+least 30x warm, valid MCP responses, matching package identity, and no leaked
+child process.
+
+Raw report:
+[`npm-mcp-boundary-mcport-0.3.0-vs-js-0.3.15.json`](https://github.com/sergii-ziborov/weavatrix-rust/blob/main/benchmark-results/npm-mcp-boundary-mcport-0.3.0-vs-js-0.3.15.json)
+(SHA-256
+`8224CACEA4F10B6B09BB525FCC1E4FFA0A7AF1292CD1C4EC63515A2CF99D7F5A`).
+
+The full methodology, historical same-revision repository measurements,
+component competitors, limitations, and reproduction commands are in the
+[benchmark report](https://github.com/sergii-ziborov/weavatrix-rust/blob/main/docs/benchmarks.md).
+
+## Quality measured against the JavaScript engine
+
+Both engines analyzed an immutable 502-file `weavatrix-js` 0.3.14 checkout.
+Paths, symbols, and relation identities were normalized before comparison.
+
+| Relation | Rust | JavaScript | JavaScript evidence covered |
+| --- | ---: | ---: | ---: |
+| imports | 2,320 | 1,126 | **100%** |
+| methods | 63 | 4 | **100%** |
+| re-exports | 80 | 75 | **100%** |
+| calls | 3,403 | 2,323 | **100% of targets** |
+
+For calls, 2,024 edges matched exactly. The remaining 299 reached the same
+source-line target while Rust also attached the containing symbol as owner.
+There were **zero missing targets and zero wrong targets**. Rust-only edges are
+retained as evidence, not automatically declared correct merely because there
+are more of them.
+
+Raw parity reports:
+
+- [`graph-parity-rust-1.0.0-vs-js-0.3.14.json`](https://github.com/sergii-ziborov/weavatrix-rust/blob/main/benchmark-results/graph-parity-rust-1.0.0-vs-js-0.3.14.json)
+- [`call-audit-rust-1.0.0-vs-js-0.3.14.json`](https://github.com/sergii-ziborov/weavatrix-rust/blob/main/benchmark-results/call-audit-rust-1.0.0-vs-js-0.3.14.json)
+
+The release also dogfoods all 39 tools against Weavatrix itself. The verified
+self-run returned `PASS` with zero health findings, zero clone families, zero
+dead-code candidates after correct `#[cfg(test)]` inheritance, and no
+architecture cycles or dependency findings.
+
+## Library and standalone CLI
+
+The MCP transport is optional. A minimal build keeps the Rust library and
+standalone `analyze`, `list-tools`, and `tool` commands without `mcport`:
+
+```toml
+[dependencies]
+weavatrix-rust = { version = "1", default-features = false }
+```
 
 ```sh
-npm install
-npm test                 # unit/integration tests plus the quick golden benchmark
-npm run benchmark        # full TS/JS/Python/Go/Java/Rust + MCP lifecycle gate
-npm run benchmark:real   # locally available real repos vs source-free 0.2.1 baselines
+cargo build --no-default-features
+weavatrix analyze . --pretty
+weavatrix list-tools
+weavatrix tool graph_stats .
 ```
 
-Maintained JavaScript/TypeScript under `src`, `bin`, `scripts`, `test` has a hard 300-line physical
-ceiling enforced by the release suite; larger concerns split into owner-focused modules behind slim
-facades. The weavatrix.com landing site lives in its own repository (`weavatrix-site`).
+Enable `mcp` only when embedding the stdio server. The default full build also
+connects the first-party scan, graph, Git, search, clone, vector, semantic, and
+memory crates.
+
+## Safety and package integrity
+
+- read-only repository analysis;
+- no install scripts or runtime downloads;
+- no application-source writes or commit creation;
+- no execution of analyzed repository code;
+- bounded MCP results with pagination for large neighborhoods and communities;
+- source-free, credential-free evidence by default;
+- npm provenance and immutable GitHub release assets;
+- forbidden unsafe Rust in the engine.
+
+## Why the JavaScript version moved
+
+The canonical npm package moved to the native Rust engine after the Rust
+implementation covered the complete shared tool contract, found all measured
+JavaScript relation targets, added five native workflows, removed external
+runtime executables, preserved lossless parser input, and passed the installed
+package speed gate.
+
+The maintained JavaScript line remains available as
+[`weavatrix-js`](https://github.com/sergii-ziborov/weavatrix-js) for extensions
+and compatibility. `weavatrix@0.3.14` is the last JavaScript release under the
+canonical package name.
 
-## Release history
+Build lineage:
 
-Per-version patch notes live in [docs/releases/](docs/releases/) — start with the newest entry there.
-The release process and gates are in [scripts/verify-release.mjs](scripts/verify-release.mjs).
+- [`weavatrix`](https://github.com/sergii-ziborov/weavatrix) — canonical npm package;
+- [`weavatrix-rust`](https://github.com/sergii-ziborov/weavatrix-rust) — native engine and crates.io source;
+- [`weavatrix-parse`](https://github.com/sergii-ziborov/weavatrix-parse) — lossless parser;
+- [`mcport`](https://github.com/sergii-ziborov/mcport) — dependency-light MCP stdio runtime.
 
 ## License
 
-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.
+MIT. Third-party crates retain their own licenses.

package/bin/resolve-binary.mjs

@@ -0,0 +1,73 @@
+// Resolves the platform-specific Weavatrix binary bundled in the universal npm
+// package. Separate platform packages remain a development/test fallback.
+// Pure Node: built-ins only, no install scripts and no network access.
+import { existsSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const PLATFORM_PACKAGES = {
+    'win32 x64': ['@weavatrix/cli-win32-x64', 'weavatrix.exe'],
+    'win32 arm64': ['@weavatrix/cli-win32-arm64', 'weavatrix.exe'],
+    'darwin x64': ['@weavatrix/cli-darwin-x64', 'weavatrix'],
+    'darwin arm64': ['@weavatrix/cli-darwin-arm64', 'weavatrix'],
+    'linux x64': ['@weavatrix/cli-linux-x64', 'weavatrix'],
+    'linux arm64': ['@weavatrix/cli-linux-arm64', 'weavatrix'],
+}
+
+const BUNDLED_BINARIES = {
+    'win32 x64': ['win32-x64', 'weavatrix.exe'],
+    'win32 arm64': ['win32-arm64', 'weavatrix.exe'],
+    'darwin x64': ['darwin-x64', 'weavatrix'],
+    'darwin arm64': ['darwin-arm64', 'weavatrix'],
+    'linux x64': ['linux-x64', 'weavatrix'],
+    'linux arm64': ['linux-arm64', 'weavatrix'],
+}
+
+export function resolveBinary() {
+    const key = `${process.platform} ${process.arch}`
+    const entry = PLATFORM_PACKAGES[key]
+    if (!entry) {
+        fail(`Unsupported platform: ${key}.`,
+            'Prebuilt binaries cover win32/darwin/linux on x64 and arm64.',
+            'On other platforms install from source: cargo install weavatrix-rust')
+    }
+    const bundled = locateBundled(key)
+    if (bundled) return bundled
+    const [packageName, binaryName] = entry
+    const binary = locate(packageName, binaryName)
+    if (binary) return binary
+    fail(`The bundled native executable for ${key} is missing.`,
+        'The installed package is incomplete; reinstall weavatrix,',
+        'or: cargo install weavatrix-rust')
+    return null
+}
+
+function locateBundled(key) {
+    const [directory, binaryName] = BUNDLED_BINARIES[key]
+    const binary = join(dirname(fileURLToPath(import.meta.url)), 'native', directory, binaryName)
+    return existsSync(binary) ? binary : null
+}
+
+// Registry installs resolve from this file's own location. The extra bases
+// keep symlinked installs working (npm file:/link: put the real files outside
+// the consumer's node_modules, and ESM canonicalizes import.meta.url).
+function locate(packageName, binaryName) {
+    const bases = [import.meta.url, process.argv[1], join(process.cwd(), 'package.json')]
+    for (const base of bases) {
+        if (!base) continue
+        try {
+            const packageJson = createRequire(base).resolve(`${packageName}/package.json`)
+            const binary = packageJson.slice(0, -'package.json'.length) + binaryName
+            if (existsSync(binary)) return binary
+        } catch (error) {
+            if (error?.code !== 'MODULE_NOT_FOUND') throw error
+        }
+    }
+    return null
+}
+
+function fail(...lines) {
+    for (const line of lines) console.error(`weavatrix: ${line}`)
+    process.exit(1)
+}

package/bin/run-native.mjs

@@ -0,0 +1,26 @@
+import { spawn } from 'node:child_process'
+import { resolveBinary } from './resolve-binary.mjs'
+
+export function runNative(command, label) {
+    const binary = resolveBinary()
+    const args = command ? [command, ...process.argv.slice(2)] : process.argv.slice(2)
+    // Node 22.15+ can replace the launcher process on POSIX. This preserves
+    // the stdio file descriptors while removing an otherwise idle wrapper
+    // process from every MCP request and from its measured memory footprint.
+    // Older Node releases and Windows retain the compatible spawn path.
+    if (['darwin', 'linux'].includes(process.platform) && typeof process.execve === 'function') {
+        process.execve(binary, [binary, ...args], process.env)
+    }
+    const child = spawn(binary, args, { stdio: 'inherit', windowsHide: true })
+    child.on('error', (error) => {
+        console.error(`${label}: failed to start native binary: ${error.message}`)
+        process.exit(1)
+    })
+    child.on('exit', (code, signal) => {
+        if (signal) process.kill(process.pid, signal)
+        process.exit(code ?? 1)
+    })
+    for (const signal of ['SIGINT', 'SIGTERM']) {
+        process.on(signal, () => child.kill(signal))
+    }
+}

package/bin/weavatrix-mcp.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
-// Weavatrix MCP stdio entry — thin launcher so npm/npx get a shebang'd bin
-// while the server itself stays a plain module. Positional args pass through:
-//   weavatrix-mcp <repoRoot> [caps]               — graph path derived automatically
-//   weavatrix-mcp <graph.json> <repoRoot> [caps]  — explicit graph file
-const {startMcpServer} = await import('../src/mcp-server.mjs')
-await startMcpServer()
+// MCP stdio entry - drop-in compatible with the JavaScript weavatrix-mcp bin:
+//   weavatrix-mcp <repoRoot> [--profile=all|code|seo]
+// Spawns the native Rust server with stdio inherited; this wrapper adds no
+// buffering, no framing, and no event-loop work between client and server.
+import { runNative } from './run-native.mjs'
+
+runNative('mcp', 'weavatrix-mcp')

package/bin/weavatrix.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+// Full Weavatrix CLI: forwards arguments verbatim to the native binary.
+import { runNative } from './run-native.mjs'
+
+runNative(null, 'weavatrix')