weavatrix 0.2.0 → 0.2.2

package/README.md

@@ -95,7 +95,7 @@ No graph yet? Ask the agent to call `rebuild_graph`; it builds the missing graph
 With the default `offline` profile (or an explicit capability set containing `retarget`),
 `open_repo` can change the active repository
 and builds a missing graph automatically. A normal
-`open_repo` call also upgrades graphs created before `0.1.4` to edge metadata v2; `build:false`
+`open_repo` also upgrades graphs that predate current typed-edge/provenance metadata; `build:false`
 probes without building and refuses a legacy graph. Retargeting is offline but intentionally changes
 the filesystem boundary for subsequent tools; select `pinned` when that boundary must not move.
 
@@ -111,6 +111,11 @@ An agent skill with recipes ships in [skill/SKILL.md](skill/SKILL.md) — instal
 compile-only edges (Rust module/use, Java imports) are reported separately where that distinction
 changes the result.
 
+Every current edge also carries versioned provenance: `EXTRACTED`, `RESOLVED`, or `INFERRED` today,
+with `EXACT_LSP` and `CONFLICT` reserved for the optional precision overlay. `graph_stats` reports
+the complete breakdown; provenance describes how the relationship was established, while the older
+`confidence` field remains for compatibility.
+
 **search / source** — `search_code` (ripgrep-backed, pure-Node fallback), `read_source` (a
 symbol's actual code in one hop), `list_endpoints` (HTTP route inventory:
 Express/Fastify/Nest/Flask/FastAPI/Go mux/Rust axum and actix-web …)
@@ -168,6 +173,39 @@ disclosed instead of silently guessed; and the server **hot-reloads its watched
 modules and catalog** when those files change — other MCP helpers and analysis engines require a
 reconnect.
 
+### 0.2.2 regression and cross-repository evidence
+
+- Permanent TS/JS/Python/Go/Java/Rust regression fixtures now gate graph correctness, output size,
+  latency, freshness, reconnect behavior and repository-target stability.
+- Every current graph edge carries versioned `EXTRACTED`, `RESOLVED`, or `INFERRED` provenance;
+  `EXACT_LSP` and `CONFLICT` are reserved for the optional precision overlay.
+- `trace_api_contract` recognizes configured and conservatively auto-discovered HTTP wrappers,
+  resolves bounded dynamic URL prefixes and can mark an unambiguous backend handler
+  `NOT_DEAD_EXTERNAL_USE` when another registered repository supplies medium/high-confidence use.
+- Real-repository verification records explicit `MISSING`, `UNBASELINED`, and `STALE` gaps instead
+  of converting absent Java/Rust or source-checkout evidence into a green result.
+- No mandatory runtime dependency was added.
+
+Full release notes: [docs/releases/v0.2.2.md](docs/releases/v0.2.2.md).
+
+### 0.2.1 bounded-output patch
+
+- `git_history top_n=N` is a hard per-collection MCP cap, including churn, hotspots and every
+  coupling list. JSON output reports `total`, `returned` and `truncated` for each collection.
+- `god_nodes` ranks production code by default, excluding classified tests and generated/build
+  artifacts; pass `include_classified:true` only when those surfaces are intentionally in scope.
+- `output_format:"text"` returns concise TextContent only. Use `output_format:"json"` when a
+  workflow needs the full stable `weavatrix.tool.v1` structured envelope.
+- `trace_api_contract` resolves bounded constant prefixes in template URLs and accepts
+  segment-aligned path fragments such as `/query` for `/edgeAnalytics/query/...`.
+- `change_impact` labels test/e2e edits as `test-only` and does not seed product blast radius from
+  them.
+- Without a saved architecture contract, `prepare_change` returns concise provisional budgets and
+  clearly labels them as non-enforceable; request `get_architecture_contract output_format:"json"`
+  only when the inferred starter contract is actually needed.
+
+Full patch notes: [docs/releases/v0.2.1.md](docs/releases/v0.2.1.md).
+
 ## Signal quality and repository configuration
 
 Weavatrix `0.2.0` reduces the most common sources of static-analysis noise while deepening Rust and
@@ -216,6 +254,34 @@ Java graphs:
   agent review queue. Public/exported methods, framework entries, decorators, dynamic loading and
   reflection lower confidence; the result always says `REVIEW_REQUIRED` and `autoDelete:false`.
 
+### HTTP clients and wrappers
+
+`trace_api_contract` recognizes built-in object clients such as `axios.get(...)`, explicit bare or
+object/member wrappers, and simple auto-discovered functions that forward a URL parameter directly
+to a known HTTP client. Auto-discovered wrappers are restricted to their bounded reverse-import
+scope; ambiguous same-name definitions are skipped and reported as incomplete evidence.
+
+Persistent per-client-repository configuration lives in `.weavatrix.json`:
+
+```json
+{
+  "httpContracts": {
+    "clientNames": ["internalHttp"],
+    "wrappers": [
+      { "call": "get", "method": "GET", "urlArgument": 0 },
+      { "object": "transport", "member": "send", "method": "POST", "urlArgument": 1 }
+    ],
+    "autoDiscoverWrappers": true
+  }
+}
+```
+
+The MCP call exposes the same ad-hoc controls as `client_names`, `client_wrappers` and
+`auto_discover_wrappers`. A medium/high-confidence client match marks the backend endpoint/handler
+`NOT_DEAD_EXTERNAL_USE`; a low-confidence match is `POSSIBLE_EXTERNAL_USE`; no match is `UNKNOWN`.
+Only an unambiguously resolved handler node can suppress a method-level dead-code candidate. The tool
+never turns missing static evidence into a `DEAD` verdict.
+
 `run_audit` makes incomplete security coverage explicit. OSV state is `OK` only after every
 supported pinned package/version for this repository was queried successfully. `PARTIAL` means
 some queries failed, the response was incomplete, the dependency fingerprint changed, or the cache
@@ -272,7 +338,8 @@ Weavatrix itself initiates outbound HTTP only from three tools; all are absent f
   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 built before `0.1.4` must be rebuilt once before syncing; V3 also refuses a stale graph so
+  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.
 
 Evidence sections carry independent `state` (`COMPLETE`, `PARTIAL`, `NOT_CHECKED`,
@@ -326,21 +393,48 @@ Graphs are derived data and never live inside your repo: the global per-user reg
 
 ```sh
 npm install
-npm test          # node --test
+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
 ```
 
-Design rule: **no source file exceeds 300 lines.** Larger concerns split into dotted-suffix modules
-behind a slim facade (`foo.js` re-exports `foo.parse.js`, `foo.report.js`, …); the MCP layer lives
+The benchmark checks representative graph correctness, complete edge provenance, cross-repository
+HTTP tracing, output bytes, latency, freshness, reconnect and active-target stability. Its budgets, semantics and intentionally
+limited claims are documented in [docs/benchmarking.md](docs/benchmarking.md).
+
+Refactoring target: keep focused implementation modules near 300 lines and split larger concerns
+into dotted-suffix modules behind a slim facade (`foo.js` re-exports `foo.parse.js`,
+`foo.report.js`, …). A few older orchestration modules remain above that target; new work should
+reduce them instead of growing new monoliths. The MCP layer lives
 in `src/mcp/` (graph context, tool entry modules, focused helpers, and the catalog/hot-reload
 loader) behind the thin stdio entry `src/mcp-server.mjs`.
 
 ## Roadmap
 
-- **Hosted graph view** on [weavatrix.com](https://weavatrix.com) — sync with one tool call, share
-  the interactive map with your team
-- **Graph-anchored memory** — agent notes pinned to nodes/modules, staleness-tracked as the code
-  under them changes
-- **CI blast radius** — `change_impact` as a PR comment
+- **Public 0.2.2 regression foundation** now has the permanent six-language golden corpus,
+  cross-repository wrapper/liveness fixture, framework/convention fixture, full MCP lifecycle gate
+  and a portable real-repository runner. Five source-free 0.2.1 real-repository baselines are
+  recorded; edge provenance is gated end-to-end. The unavailable Rust source checkout is the only
+  explicit local gap preventing the strict six-repository release command from passing here.
+- **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.
+- **Semantic precision bridge** — optional local language-server validation for
+  ambiguous impact, reference and dead-code evidence; the current parser graph
+  remains the offline fallback.
+- **Git-native architecture history** — bounded tag/ref timelines and branch
+  reports built outside the worktree; graph artifacts stay out of Git.
+- **Cross-repository company evidence** — endpoints, events and internal
+  packages joined to affected consumers and ownership without uploading source.
+- **CI blast radius** — bounded `change_impact` and architecture-ratchet evidence
+  as a PR check/comment.
+
+The public alignment note for the fixed cross-product release sequence is in
+[docs/product-roadmap.md](docs/product-roadmap.md).
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "weavatrix",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "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.",
   "author": "Sergii Ziborov <sergii.ziborov@gmail.com>",
@@ -30,6 +30,10 @@
   ],
   "scripts": {
     "test": "node --test",
+    "benchmark": "node scripts/run-benchmark.mjs",
+    "benchmark:quick": "node scripts/run-benchmark.mjs --quick",
+    "benchmark:real": "node scripts/run-real-benchmark.mjs",
+    "benchmark:real:release": "node scripts/run-real-benchmark.mjs --require-all",
     "build:mcpb": "node scripts/build-mcpb.mjs",
     "verify:release": "node scripts/verify-release.mjs"
   },

package/skill/SKILL.md

@@ -47,6 +47,11 @@ named profiles for new registrations.
   `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.
+- **Edge provenance**: distinguish how an edge was established from legacy confidence. Current
+  graphs use `EXTRACTED`, `RESOLVED`, and `INFERRED`; `EXACT_LSP` is reserved for a bounded local
+  precision overlay and `CONFLICT` means evidence disagrees. Treat `INFERRED` and `CONFLICT` as
+  review signals rather than compiler-exact facts; an `UNKNOWN` count in `graph_stats` requires a
+  rebuild before precision-sensitive work.
 - **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. Repository-root `.weavatrixignore` applies the same tracked-file
@@ -84,7 +89,9 @@ named profiles for new registrations.
 
 ## Recipes
 
-- **Orient in the configured repo**: `module_map` → `list_communities` → `god_nodes`.
+- **Orient in the configured repo**: `module_map` → `list_communities` → `god_nodes`. Hub ranking
+  is production-only by default; use `include_classified:true` only when tests/generated/build
+  surfaces are deliberately part of the question.
 - **Refactor safety for one symbol**: `get_dependents` → `coverage_map` (low coverage × many
   dependents ⇒ write tests first) → `read_source`.
 - **Pre-PR review of your current changes**: `change_impact` (auto merge-base; includes uncommitted
@@ -114,14 +121,34 @@ named profiles for new registrations.
 - **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.
+  or backend `changed_files`. `path` may be a segment-aligned fragment (`/query` can select
+  `/edgeAnalytics/query/...`), and bounded constant prefixes in template URLs are resolved. The tool
+  recognizes configured and conservatively auto-discovered HTTP wrappers; use per-repository
+  `.weavatrix.json` `httpContracts` configuration for durable custom client names/wrappers, or
+  `client_names` / `client_wrappers` for one trace. `NOT_DEAD_EXTERNAL_USE` requires medium/high
+  confidence; only an unambiguously resolved handler node can suppress a dead-method candidate.
+  `POSSIBLE_EXTERNAL_USE`, `UNKNOWN`, and remaining unresolved/dynamic URLs are incomplete evidence,
+  never proof that a method is dead.
+- **Release regression gate**: for a Weavatrix source checkout, use `npm test` for the quick
+  six-language golden corpus and `npm run benchmark` before release for the real MCP
+  `full -> incremental -> none -> reconnect/none` lifecycle, bounded output and active-target checks.
+  Use `npm run benchmark:real` for available manifest repositories and
+  `npm run benchmark:real:release` only when all six source checkouts are present; `MISSING`,
+  `UNBASELINED` and `STALE` are explicit incomplete states, not green results.
+  A green Java/Rust fixture proves only its declared representative signals, not compiler-exact
+  coverage of arbitrary repositories.
 - **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.
+  proposal from `get_architecture_contract output_format:"json"`, not an automatically approved
+  architecture. Without a contract, `prepare_change` still returns provisional no-regression
+  budgets, but they are guidance rather than enforceable policy. 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.
+  co-change coupling from bounded local numstat history. Always set `top_n`; it is enforced across
+  every returned structured collection and JSON reports per-collection truncation. Use it as review
+  evidence, not proof that two files must be merged.
+- **Machine output**: keep the default `output_format:"text"` for concise agent conversations; opt
+  into `output_format:"json"` only when a workflow consumes the full `weavatrix.tool.v1` envelope.
 - **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).
@@ -161,7 +188,7 @@ runtime/type-only/compile-only module dependencies. Package evidence contains a
 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
+compatibility—Weavatrix never silently downgrades. A graph predating current provenance metadata, 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`.
 

package/src/analysis/change-classification.js

@@ -4,6 +4,7 @@
 // from flooding the report with every legacy importer of that file.
 import { spawnSync } from "node:child_process";
 import { childProcessEnv } from "../child-env.js";
+import { createPathClassifier, hasPathClass } from "../path-classification.js";
 
 const DEFAULT_LIMITS = Object.freeze({
   maxDiffBytes: 2 * 1024 * 1024,
@@ -15,6 +16,7 @@ const DEFAULT_LIMITS = Object.freeze({
 });
 const CLASS_RANK = Object.freeze({
   "metadata-only": 0,
+  "test-only": 0,
   added: 1,
   "body-changed": 2,
   "signature-changed": 3,
@@ -395,6 +397,20 @@ function unknownFile(path, indexed, reason) {
   };
 }
 
+function classifyTestSurface(file, pathClassifier) {
+  const explanation = pathClassifier.explain(file.path);
+  if (!hasPathClass(explanation, "test", "e2e")) return file;
+  const surface = explanation.classes.includes("e2e") ? "e2e" : "test";
+  return {
+    ...file,
+    classification: "test-only",
+    changeClassification: file.classification,
+    reason: `${surface} path; excluded from the product blast-radius seed set`,
+    pathClasses: explanation.classes,
+    seedIds: [],
+  };
+}
+
 function runGitDiff(repoRoot, base, _files, limits) {
   const args = ["-C", repoRoot, "diff", "--no-ext-diff", "--find-renames", "--no-color", "--unified=0", String(base), "--"];
   const result = spawnSync("git", args, {
@@ -443,17 +459,25 @@ export function classifyChangeImpact({
   }
 
   const indexed = graphIndex(graph, limits);
+  const pathClassifier = createPathClassifier(repoRoot);
   const parsed = available ? parseZeroContextDiff(text, limits) : { files: [], changedLines: 0, byteLength: 0, truncated: gitOversized, oversized: gitOversized, limits };
-  const analyzed = parsed.files.map((file) => analyzeParsedFile(file, indexed, { includeAddedSeeds }));
+  const analyzed = parsed.files.map((file) => classifyTestSurface(
+    analyzeParsedFile(file, indexed, { includeAddedSeeds }),
+    pathClassifier,
+  ));
   const represented = new Set(analyzed.flatMap((file) => [file.oldPath, file.newPath].filter(Boolean)));
   for (const file of explicitFiles) {
-    if (!represented.has(file)) analyzed.push(unknownFile(file, indexed, available ? "explicitly changed file had no textual hunk" : unavailableReason));
+    if (!represented.has(file)) analyzed.push(classifyTestSurface(
+      unknownFile(file, indexed, available ? "explicitly changed file had no textual hunk" : unavailableReason),
+      pathClassifier,
+    ));
   }
   if (!available && !explicitFiles.length) analyzed.push(unknownFile("(diff unavailable)", indexed, unavailableReason));
   analyzed.sort((a, b) => a.path.localeCompare(b.path));
 
   if (parsed.truncated || parsed.oversized || gitOversized) {
     for (const file of analyzed) {
+      if (file.classification === "test-only") continue;
       file.classification = "unknown";
       file.reason = "diff was truncated/oversized; symbol-level classification is incomplete";
       const record = indexed.get(file.newPath) || indexed.get(file.oldPath);
@@ -480,6 +504,7 @@ export function classifyChangeImpact({
   if (counts["body-changed"]) reasons.push(`${counts["body-changed"]} file(s) contain mapped executable body changes.`);
   if (counts.added && !includeAddedSeeds) reasons.push(`${counts.added} purely additive file change(s) create no dependent seeds by default.`);
   if (counts["metadata-only"]) reasons.push(`${counts["metadata-only"]} metadata-only file change(s) create no dependent seeds.`);
+  if (counts["test-only"]) reasons.push(`${counts["test-only"]} test-only file change(s) are labelled explicitly and create no product blast-radius seeds.`);
   if (counts.unknown) reasons.push(`${counts.unknown} file change(s) remain unknown and are seeded conservatively.`);
   if (!reasons.length) reasons.push("No changed files were present in the supplied diff.");
 

package/src/analysis/git-history.js

@@ -547,3 +547,45 @@ export function formatGitHistoryAnalytics(result, options = {}) {
   if (result.completeness.reasons.length) lines.push("", `Partial: ${result.completeness.reasons.join("; ")}.`);
   return lines.join("\n");
 }
+
+// Keep the full analytics object available to local callers, but never expose its unbounded
+// collections through an MCP response. `topN` is a per-collection ceiling, not merely a text
+// formatting hint. The accompanying page metadata lets machine consumers distinguish "there were
+// no more results" from "more evidence exists but was deliberately omitted".
+export function boundGitHistoryAnalytics(result, options = {}) {
+  const topN = boundedInteger(options.topN, 10, 1, 50);
+  const source = result && typeof result === "object" ? result : {};
+  const coupling = source.coupling && typeof source.coupling === "object" ? source.coupling : {};
+  const collections = {};
+  const cap = (name, value) => {
+    const items = Array.isArray(value) ? value : [];
+    const bounded = items.slice(0, topN);
+    collections[name] = {
+      total: items.length,
+      returned: bounded.length,
+      truncated: items.length > bounded.length,
+    };
+    return bounded;
+  };
+
+  const bounded = {
+    ...source,
+    limits: {...(source.limits || {}), topN},
+    fileChurn: cap("fileChurn", source.fileChurn),
+    hotspots: cap("hotspots", source.hotspots),
+    coupling: {
+      ...coupling,
+      observed: cap("coupling.observed", coupling.observed),
+      expectedTestSource: cap("coupling.expectedTestSource", coupling.expectedTestSource),
+      hidden: cap("coupling.hidden", coupling.hidden),
+    },
+  };
+  return {
+    result: bounded,
+    page: {
+      limit: topN,
+      truncated: Object.values(collections).some((entry) => entry.truncated),
+      collections,
+    },
+  };
+}

package/src/analysis/http-contract-wrappers.js

@@ -0,0 +1,232 @@
+// Bounded HTTP-wrapper configuration and conservative auto-discovery. A wrapper is accepted only
+// when its URL position and HTTP method are statically known; no source is evaluated.
+import { statSync } from "node:fs";
+import { createRepoBoundary } from "../repo-path.js";
+import { safeRead } from "../util.js";
+
+export const DEFAULT_HTTP_CLIENT_NAMES = Object.freeze([
+  "axios", "http", "https", "$http", "httpClient", "apiClient", "restClient",
+]);
+
+const HTTP_METHODS = new Set(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]);
+const MAX_CONFIG_BYTES = 64 * 1024;
+const MAX_WRAPPERS = 100;
+const MAX_CLIENT_NAMES = 40;
+const MAX_DISCOVERY_BODY = 2_000;
+const identifier = (value) => {
+  const text = String(value || "").trim();
+  return /^[A-Za-z_$][\w$]{0,127}$/.test(text) ? text : null;
+};
+const method = (value) => {
+  const text = String(value || "").trim().toUpperCase();
+  return HTTP_METHODS.has(text) ? text : null;
+};
+const argumentIndex = (value) => {
+  const number = Number(value ?? 0);
+  return Number.isInteger(number) && number >= 0 && number <= 5 ? number : null;
+};
+
+export function normalizeHttpClientNames(values) {
+  return [...new Set((Array.isArray(values) ? values : [])
+    .slice(0, MAX_CLIENT_NAMES)
+    .map(identifier)
+    .filter(Boolean))];
+}
+
+export function normalizeHttpWrapperDescriptors(values, source = "input") {
+  const wrappers = [];
+  for (const raw of (Array.isArray(values) ? values : []).slice(0, MAX_WRAPPERS)) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) continue;
+    const urlArgument = argumentIndex(raw.urlArgument ?? raw.url_argument);
+    const fixedMethod = method(raw.method);
+    if (urlArgument == null || !fixedMethod) continue;
+    const call = identifier(raw.call);
+    const object = identifier(raw.object);
+    const member = identifier(raw.member);
+    if (call && !object && !member) {
+      wrappers.push({ kind: "function", call, method: fixedMethod, urlArgument, source });
+    } else if (!call && object && member) {
+      wrappers.push({ kind: "member", object, member, method: fixedMethod, urlArgument, source });
+    }
+  }
+  const seen = new Set();
+  return wrappers.filter((wrapper) => {
+    const key = `${wrapper.kind}\0${wrapper.call || wrapper.object}\0${wrapper.member || ""}\0${wrapper.method}\0${wrapper.urlArgument}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+export function loadHttpContractConfig(repoRoot) {
+  const empty = { clientNames: [], wrappers: [], autoDiscoverWrappers: true, loaded: false, warnings: [] };
+  const resolved = createRepoBoundary(repoRoot).resolve(".weavatrix.json");
+  if (!resolved.ok) return empty;
+  try {
+    if (statSync(resolved.path).size > MAX_CONFIG_BYTES) return { ...empty, error: "config-too-large" };
+    const raw = JSON.parse(safeRead(resolved.path));
+    const config = raw?.httpContracts;
+    if (config == null) return { ...empty, loaded: true };
+    if (!config || typeof config !== "object" || Array.isArray(config)) return { ...empty, error: "invalid-http-contract-config" };
+    const rawNames = Array.isArray(config.clientNames) ? config.clientNames : [];
+    const rawWrappers = Array.isArray(config.wrappers) ? config.wrappers : [];
+    const clientNames = normalizeHttpClientNames(rawNames);
+    const wrappers = normalizeHttpWrapperDescriptors(rawWrappers, "config");
+    const warnings = [];
+    if (config.clientNames != null && !Array.isArray(config.clientNames)) warnings.push("httpContracts.clientNames must be an array");
+    if (rawNames.length > MAX_CLIENT_NAMES) warnings.push("httpContracts.clientNames cap reached");
+    if (clientNames.length < Math.min(rawNames.length, MAX_CLIENT_NAMES)) warnings.push("invalid httpContracts.clientNames entries skipped");
+    if (config.wrappers != null && !Array.isArray(config.wrappers)) warnings.push("httpContracts.wrappers must be an array");
+    if (rawWrappers.length > MAX_WRAPPERS) warnings.push("httpContracts.wrappers cap reached");
+    if (wrappers.length < Math.min(rawWrappers.length, MAX_WRAPPERS)) warnings.push("invalid or duplicate httpContracts.wrappers entries skipped");
+    if (config.autoDiscoverWrappers != null && typeof config.autoDiscoverWrappers !== "boolean") warnings.push("httpContracts.autoDiscoverWrappers must be boolean");
+    return {
+      clientNames,
+      wrappers,
+      autoDiscoverWrappers: config.autoDiscoverWrappers !== false,
+      loaded: true,
+      warnings,
+    };
+  } catch {
+    return { ...empty, error: "invalid-config" };
+  }
+}
+
+// Masks comments and strings while retaining indices and newlines. Wrapper discovery needs only
+// declarations and a direct `client.verb(urlParam)` delegation, never literal contents.
+function codeMask(text) {
+  const chars = String(text || "").split("");
+  let index = 0;
+  while (index < chars.length) {
+    const char = chars[index], next = chars[index + 1];
+    if (char === "/" && next === "/") {
+      chars[index++] = " "; chars[index++] = " ";
+      while (index < chars.length && chars[index] !== "\n") chars[index++] = " ";
+    } else if (char === "/" && next === "*") {
+      chars[index++] = " "; chars[index++] = " ";
+      while (index < chars.length) {
+        if (chars[index] === "*" && chars[index + 1] === "/") { chars[index++] = " "; chars[index++] = " "; break; }
+        if (chars[index] !== "\n") chars[index] = " ";
+        index += 1;
+      }
+    } else if (char === "'" || char === '"' || char === "`") {
+      const quote = char;
+      chars[index++] = " ";
+      while (index < chars.length) {
+        if (chars[index] === "\\") {
+          chars[index++] = " ";
+          if (index < chars.length && chars[index] !== "\n") chars[index] = " ";
+          index += 1;
+          continue;
+        }
+        const closes = chars[index] === quote;
+        if (chars[index] !== "\n") chars[index] = " ";
+        index += 1;
+        if (closes) break;
+      }
+    } else index += 1;
+  }
+  return chars.join("");
+}
+
+function matchingBrace(mask, open) {
+  let depth = 0;
+  for (let index = open; index < Math.min(mask.length, open + MAX_DISCOVERY_BODY); index += 1) {
+    if (mask[index] === "{") depth += 1;
+    else if (mask[index] === "}" && --depth === 0) return index + 1;
+  }
+  return Math.min(mask.length, open + MAX_DISCOVERY_BODY);
+}
+
+function parameterNames(raw) {
+  const parts = [];
+  let start = 0, round = 0, square = 0, curly = 0, angle = 0;
+  const text = String(raw || "");
+  for (let index = 0; index <= text.length; index += 1) {
+    const char = text[index];
+    if (char === "(") round += 1;
+    else if (char === ")") round -= 1;
+    else if (char === "[") square += 1;
+    else if (char === "]") square -= 1;
+    else if (char === "{") curly += 1;
+    else if (char === "}") curly -= 1;
+    else if (char === "<") angle += 1;
+    else if (char === ">") angle = Math.max(0, angle - 1);
+    if ((char === "," && round === 0 && square === 0 && curly === 0 && angle === 0) || index === text.length) {
+      parts.push(text.slice(start, index));
+      start = index + 1;
+    }
+  }
+  const names = [];
+  for (const part of parts.slice(0, 6)) {
+    const match = /^\s*([A-Za-z_$][\w$]*)(?=\s*(?:[?:=]|$))/.exec(part);
+    if (!match) return [];
+    names.push(match[1]);
+  }
+  return names;
+}
+
+function escaped(value) {
+  return String(value).replace(/[|\\{}()[\]^$+*?.-]/g, "\\$&");
+}
+
+function delegatedWrapper(mask, definition, clientNames) {
+  const body = mask.slice(definition.bodyStart, definition.bodyEnd);
+  const clients = clientNames.map(escaped).join("|");
+  if (!clients) return null;
+  const delegate = new RegExp(`\\b(?:${clients})\\s*(?:\\?\\.|\\.)\\s*(get|post|put|patch|delete|head|options)\\s*(?:<[^>\\n]{1,200}>)?\\s*\\(\\s*([A-Za-z_$][\\w$]*)\\s*(?=[,)])`, "gi");
+  const matches = [];
+  let found;
+  while ((found = delegate.exec(body)) && matches.length < 3) {
+    const urlArgument = definition.parameters.indexOf(found[2]);
+    if (urlArgument >= 0) matches.push({ method: found[1].toUpperCase(), urlArgument });
+  }
+  const unique = [...new Map(matches.map((item) => [`${item.method}\0${item.urlArgument}`, item])).values()];
+  return unique.length === 1 ? unique[0] : null;
+}
+
+export function discoverHttpWrappers(sources, clientNames = []) {
+  const allowedClients = [...new Set([...DEFAULT_HTTP_CLIENT_NAMES, ...normalizeHttpClientNames(clientNames)])];
+  const candidates = [];
+  let truncated = false;
+  for (const source of Array.isArray(sources) ? sources : []) {
+    if (candidates.length >= MAX_WRAPPERS) { truncated = true; break; }
+    const mask = codeMask(source.text);
+    const definitions = [];
+    const functions = /\b(?:export\s+)?(?:default\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)\s*\(([^)]{0,300})\)\s*(?::[^\n{]{1,200})?\s*\{/g;
+    let match;
+    while ((match = functions.exec(mask)) && definitions.length < MAX_WRAPPERS) {
+      const open = functions.lastIndex - 1;
+      definitions.push({ call: match[1], parameters: parameterNames(match[2]), bodyStart: open + 1, bodyEnd: matchingBrace(mask, open) - 1 });
+    }
+    const arrows = /\b(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s+)?(?:<[^>\n]{1,200}>\s*)?(?:\(([^)]{0,300})\)\s*(?::[^\n=]{1,200})?|([A-Za-z_$][\w$]*))\s*=>\s*/g;
+    while ((match = arrows.exec(mask)) && definitions.length < MAX_WRAPPERS) {
+      const parameters = parameterNames(match[2] ?? match[3]);
+      const open = mask.indexOf("{", arrows.lastIndex);
+      const block = open >= 0 && /^\s*\{/.test(mask.slice(arrows.lastIndex, open + 1));
+      const bodyStart = block ? open + 1 : arrows.lastIndex;
+      const bodyEnd = block ? matchingBrace(mask, open) - 1 : Math.min(mask.length, bodyStart + MAX_DISCOVERY_BODY, mask.indexOf(";", bodyStart) >= 0 ? mask.indexOf(";", bodyStart) : mask.length);
+      definitions.push({ call: match[1], parameters, bodyStart, bodyEnd });
+    }
+    for (const definition of definitions) {
+      if (!definition.parameters.length) continue;
+      const delegated = delegatedWrapper(mask, definition, allowedClients);
+      if (delegated && candidates.length < MAX_WRAPPERS) candidates.push({ kind: "function", call: definition.call, ...delegated, source: "auto", definitionFile: source.file });
+      else if (delegated) truncated = true;
+    }
+  }
+
+  const byCall = new Map();
+  for (const candidate of candidates) {
+    const entries = byCall.get(candidate.call) || [];
+    entries.push(candidate);
+    byCall.set(candidate.call, entries);
+  }
+  const wrappers = [], ambiguous = [];
+  for (const [call, entries] of [...byCall.entries()].sort(([left], [right]) => left.localeCompare(right))) {
+    const unique = [...new Map(entries.map((entry) => [`${entry.method}\0${entry.urlArgument}\0${entry.definitionFile}`, entry])).values()];
+    if (unique.length === 1) wrappers.push(unique[0]);
+    else ambiguous.push({ call, definitions: unique.length });
+  }
+  return { wrappers, ambiguous, truncated };
+}