weavatrix 0.2.18 → 0.3.0

package/skill/SKILL.md

@@ -6,7 +6,7 @@ description: "Use the Weavatrix MCP as a reusable local repository-intelligence
 # weavatrix MCP
 
 Structure-analysis tools over a prebuilt code graph plus the weavatrix analysis engines. The default
-`offline` profile has every HTTP tool disabled and permits repository switching only through an
+`offline` profile contains no HTTP tool and permits repository switching only through an
 explicit local `open_repo` call. Use `pinned` when a shared MCP process must never change or inspect
 outside its startup repository.
 
@@ -17,27 +17,21 @@ Tools are named `mcp__weavatrix__…`. If none are available, ask the user to re
 `codex mcp add weavatrix -- npx -y weavatrix <repoRoot>`), then retry.
 
 First compare the selected profile with the `graph_stats` runtime line. Expected catalogs are 31
-tools for `pinned`, 34 for `offline`, 35 for `osv`, and 38 for `hosted` / `full`. Weavatrix refuses
+tools for `pinned` and 34 for `offline`. Weavatrix refuses
 `initialize`, `tools/list`, and tool calls when the running package version differs from the
 `package.json` version on disk, with a loud `STALE_RUNTIME` error; restart/reconnect rather than using
 an old daemon. `WEAVATRIX_ALLOW_STALE_RUNTIME=1` is only for deliberate source development. A custom
-capability list needs `crossrepo` for `trace_api_contract`; legacy `online` adds only
-`advisories,hosted`. Missing HTTP tools are intentional only when the selected profile excludes them.
+capability list needs `crossrepo` for `trace_api_contract`. Legacy network profile names fail loudly
+and direct the user to the separate `weavatrix-online` package.
 
 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 local-only `preview_sync` and the explicitly invoked network tools
-  `pull_architecture_contract` and confirmed `sync_graph`.
-
-The legacy `online` capability remains a compatibility alias for `advisories,hosted`; prefer the
-named profiles for new registrations.
 
 ## Intent router
 
-Weavatrix is not one report or three fixed workflows. Its 38 methods expose different bounded views
+Weavatrix is not one report or three fixed workflows. Its 34 methods expose different bounded views
 and analyses over the same reusable graph. Start from the task and choose the smallest sufficient
 projection; expand only when the answer requires it.
 
@@ -95,20 +89,26 @@ projection; expand only when the answer requires it.
   a changed file remains existing.
 - **Review dependency declarations/imports**: `run_audit category=dependencies`; it includes missing,
   unused, duplicate, unresolved-import and lockfile-drift evidence without relabelling identities.
-  Maven/Gradle manifests are inventoried but unsupported import-to-artifact verification is reported
-  `NOT_SUPPORTED`/`PARTIAL`, never a false clean `0 declared / 0 external`.
-- **Refresh vulnerability evidence when explicitly authorized**: `refresh_advisories`, then
-  `run_audit category=vulnerability`. `NOT_CHECKED` is unknown, never clean.
-- **Review dead files, functions, methods and symbols**: `find_dead_code`; every result remains a
-  review candidate with framework/dynamic/public-API caveats, never an auto-delete verdict.
+  Maven/Gradle imports are mapped to exact artifact ownership when the referenced class is present in
+  an already installed local JAR. Missing artifacts, ambiguous class owners, version catalogs or
+  dynamic build logic remain `PARTIAL`/`NOT_SUPPORTED`, never a false clean `0 declared / 0 external`.
+- **Review vulnerability evidence**: `run_audit category=vulnerability`. `NOT_CHECKED` is unknown,
+  never clean; remote refresh is an explicit `weavatrix-online` workflow.
+  - **Review dead files, functions, methods and symbols**: `find_dead_code`; every result remains a
+    review candidate with framework/dynamic/public-API caveats, never an auto-delete verdict.
+  - **Trace dynamic GraphQL/gRPC/Kafka contracts**: export a source-free
+    `weavatrix.transport-runtime.v1` JSON report (normalized observations or OTLP `resourceSpans`) to
+    `.weavatrix/transport-runtime.json`, rebuild the graph, and call `trace_api_contract`. Only a
+    fresh report whose `repositoryRevision` matches `graphRevision` and whose observation maps to the
+    dynamic file/line resolves that `UNKNOWN`; missing capture remains unknown.
 - **Review clone families or same-name divergence**: `find_duplicates`; framework router boilerplate
-  is suppressed unless explicitly requested.
+  and immutable declarative catalog shapes stay suppressed unless explicitly included.
 - **Map measured coverage or honest static test reachability**: `coverage_map`; unavailable measured
   coverage is not 0%.
 - **Prioritize local performance-review candidates**: `hot_path_review`; confirm with a profiler or
   benchmark before changing runtime behavior.
 
-### Intended architecture and Hosted governance
+### Intended architecture
 
 - **Read or establish intended architecture**: `get_architecture_contract`. A returned starter adapts
   to Maven/Gradle source roots and monorepos and proposes product-code territories plus observed
@@ -123,11 +123,8 @@ projection; expand only when the answer requires it.
   `verify_architecture`.
 - **Understand or request an exception**: `explain_architecture_violation` ->
   `propose_architecture_exception`; proposals never mutate policy automatically. After human approval,
-  the owner must add the returned proposal to the local contract's `exceptions` or approve it in Hosted.
-- **Pull an owner-approved Hosted target**: `pull_architecture_contract` only in an explicitly enabled
-  Hosted profile.
-- **Review exactly what Hosted sync would send**: `preview_sync`; only an approved
-  `sync_graph dry_run=false confirm_token=...` may send that exact bounded payload.
+  the owner must add the returned proposal to the local contract's `exceptions`; remote governance
+  belongs to `weavatrix-online`.
 
 Across every scenario, treat `PARTIAL`, `UNAVAILABLE`, `OFF`, `NOT_SUPPORTED`, `NOT_CHECKED`,
 `ERROR`, or capped evidence as incomplete rather than success. Java and Rust exact language-server
@@ -196,22 +193,14 @@ interface dispatch, reflection, or runtime behavior.
   ecosystem is not a repository-wide clean zero. For OSV, `OK` is
   complete for the recorded dependency fingerprint; `PARTIAL` is incomplete or stale,
   `NOT_CHECKED` has no repository-specific result, and `ERROR` means the local check failed. Treat
-  the same non-`OK` states as incomplete for malware scanning. Refresh OSV only when the user has
-  authorized selecting the optional `osv` profile (or `advisories` capability) and then
-  invoking `refresh_advisories`; enabling the group alone sends nothing.
+  the same non-`OK` states as incomplete for malware scanning. Remote OSV refresh belongs to the
+  separate `weavatrix-online` package; this MIT core reads only its validated local cache.
 - **Offline by design**: scans and graph queries use local files; the semantic overlay may launch
   Weavatrix's bundled read-only TypeScript language-server child process, but it never runs repository
   scripts or downloads a provider. Coverage tools read existing reports and never run tests. The
-  ONLY network-touching tools live in the optional
-  `advisories` / `hosted` capabilities and run solely when explicitly called:
-  `refresh_advisories` (queries OSV.dev with
-  package names + versions so `run_audit` has fresh vulnerability data) and `sync_graph` (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
-  stable UUID, downloads the owner-approved contract, validates it, and caches it locally; it requires
-  `WEAVATRIX_SYNC_URL` and `WEAVATRIX_SYNC_TOKEN`. All three are absent from the default profile.
+  package contains no network-touching tool or network-enabled profile. Online/Cloud/Enterprise work
+  uses the separate `weavatrix-online` superset, which depends on this core and may add tools, skills
+  and local analyzer providers without replacing core implementations.
 - **Repository boundary**: source reads and graph-derived paths are realpath-contained. `open_repo`
   intentionally changes the active boundary through an explicit offline tool call. It is included in
   `offline`, absent from `pinned`, and available in a custom registration only when `retarget` is
@@ -362,34 +351,20 @@ dependency findings when every use is inside those roots; graph edges, cycles an
 visible. `managedDependencies` documents modules provided outside the repo's Python manifest;
 `ignoreDependencies` suppresses intentionally unresolved imports.
 
-## Sync
-
-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
-runtime/type-only/compile-only module dependencies. Package evidence contains a bounded lockfile
-graph with direct/transitive runtime, dev, optional and peer edges plus explicit resolution counts.
-Duplicate evidence contains stable, source-free clone/divergence candidates; it never sends method
-bodies or snippets. Use `payload_version: 2` only when the user explicitly wants graph-only
-compatibility—Weavatrix never silently downgrades. A graph 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`.
+## Online extensions
+
+This package is the MIT, network-free core. If `refresh_advisories`, `online_status`, `preview_sync`,
+`pull_architecture_contract` or `sync_graph` is required, use the separately installed
+`weavatrix-online` MCP and follow its skill. Do not attempt to enable a legacy profile here: the
+`online`, `osv`, `hosted` and `full` names fail loudly and cannot add network code to this artifact.
 
 ## Troubleshooting
 
 - `Graph unavailable` → `rebuild_graph`; normal graph/health calls automatically refresh an existing
   graph and report `none`, `incremental`, or `full`. `open_repo` can select another valid repository path unless
   the registration deliberately omitted `retarget`.
-- `refresh_advisories` is unavailable → with the user's approval, re-register/reconfigure the MCP
-  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.
-- `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.
+- An Online-only tool is unavailable → keep this core registration network-free and configure the
+  separate `weavatrix-online` MCP only when the user actually wants Cloud or Enterprise integration.
 - `No coverage report` → run the repo's own tests with coverage (`vitest run --coverage`,
   `jest --coverage`, `pytest --cov --cov-report=json`, `go test -coverprofile=coverage.out`),
   then re-call.

package/src/analysis/architecture/contract-storage.js

@@ -21,12 +21,12 @@ export function loadArchitectureContract(repoRoot, graphPath) {
     }
     const cached = graphPath ? join(dirname(graphPath), 'architecture.contract.json') : null
     return cached && existsSync(cached)
-        ? readContract(cached, 'hosted-cache')
+        ? readContract(cached, 'extension-cache')
         : {contract: null, source: null, error: null}
 }
 
 export function writeCachedArchitectureContract(graphPath, input) {
-    if (!graphPath) throw new Error('graph path is required for hosted contract cache')
+    if (!graphPath) throw new Error('graph path is required for extension contract cache')
     const contract = normalizeArchitectureContract(input)
     const path = join(dirname(graphPath), 'architecture.contract.json')
     mkdirSync(dirname(path), {recursive: true})

package/src/analysis/audit-extensions.js

@@ -0,0 +1,60 @@
+import {sortFindings, summarizeFindings} from './findings.js'
+
+const VALID_STATUS = new Set(['CHECKED', 'NOT_CHECKED', 'PARTIAL', 'ERROR', 'NOT_SUPPORTED'])
+const VALID_COMPLETENESS = new Set(['COMPLETE', 'PARTIAL'])
+
+const providerFailure = (provider, reason) => ({
+    id: provider.id,
+    extension: provider.extension || null,
+    status: 'ERROR',
+    completeness: 'PARTIAL',
+    detail: reason,
+    findings: [],
+})
+
+const normalizeResult = (provider, value) => {
+    if (!value || typeof value !== 'object') return providerFailure(provider, 'provider returned no result envelope')
+    const status = VALID_STATUS.has(value.status) ? value.status : 'ERROR'
+    const completeness = VALID_COMPLETENESS.has(value.completeness) ? value.completeness : 'PARTIAL'
+    const findings = Array.isArray(value.findings) ? value.findings.map((finding) => ({
+        ...finding,
+        source: finding?.source || `extension:${provider.extension || provider.id}`,
+    })) : []
+    return {
+        id: provider.id,
+        extension: provider.extension || null,
+        status,
+        completeness,
+        detail: String(value.detail || (status === 'ERROR' ? 'provider returned an invalid status' : 'extension analyzer completed')),
+        findings,
+        evidence: value.evidence ?? null,
+    }
+}
+
+// Extension analyzers are deliberately local. A provider failure stays explicit ERROR/PARTIAL and
+// never converts missing evidence into a clean result for the core audit.
+export async function applyAuditExtensions(coreAudit, {providers = [], repoRoot, graph, args = {}} = {}) {
+    if (!coreAudit?.ok || !providers.length) return coreAudit
+    const results = []
+    for (const provider of providers) {
+        try {
+            const value = await provider.run({repoRoot, graph, args, coreAudit})
+            results.push(normalizeResult(provider, value))
+        } catch (error) {
+            results.push(providerFailure(provider, error instanceof Error ? error.message : String(error)))
+        }
+    }
+    const findings = sortFindings([
+        ...coreAudit.findings,
+        ...results.flatMap((result) => result.findings),
+    ])
+    return {
+        ...coreAudit,
+        findings,
+        summary: summarizeFindings(findings),
+        extensionCapabilities: results.map(({findings: providerFindings, ...result}) => ({
+            ...result,
+            findingCount: providerFindings.length,
+        })),
+    }
+}

package/src/analysis/duplicate-groups.js

@@ -44,6 +44,11 @@ export function isFrameworkBoilerplateCloneGroup(group) {
     && /^(?:router|routes)\(?\)?$/i.test(String(member.label || '').trim()))
 }
 
+export function isDeclarativeCatalogCloneGroup(group) {
+  const members = Array.isArray(group?.members) ? group.members : []
+  return members.length >= 2 && members.every((member) => member.declarative === true)
+}
+
 export function analyzeDuplicateGroups(repoRoot, graphPath, args = {}) {
   const settings = {
     simMin: Math.min(100, Math.max(50, Number(args.min_similarity) || 80)),
@@ -52,12 +57,18 @@ export function analyzeDuplicateGroups(repoRoot, graphPath, args = {}) {
     skipTests: args.include_tests !== true,
     includeClassified: args.include_classified === true || args.include_non_product === true,
     includeBoilerplate: args.include_boilerplate === true,
+    includeDeclarative: args.include_declarative === true,
   }
   const data = computeDuplicates(repoRoot, graphPath, {includeStrings: args.include_strings === true, minTokens: settings.tokMin})
   const allGroups = groupPairs(data, settings)
-  const groups = settings.includeBoilerplate ? allGroups : allGroups.filter((group) => !isFrameworkBoilerplateCloneGroup(group))
+  const afterBoilerplate = settings.includeBoilerplate ? allGroups : allGroups.filter((group) => !isFrameworkBoilerplateCloneGroup(group))
+  const groups = settings.includeDeclarative ? afterBoilerplate : afterBoilerplate.filter((group) => !isDeclarativeCatalogCloneGroup(group))
   const suppressed = (data.frags || []).filter((fragment) => !eligible(fragment, settings)).length
-  return {settings, groups, suppressed, boilerplateSuppressed: allGroups.length - groups.length}
+  return {
+    settings, groups, suppressed,
+    boilerplateSuppressed: allGroups.length - afterBoilerplate.length,
+    declarativeSuppressed: afterBoilerplate.length - groups.length,
+  }
 }
 
 const digest = (value) => createHash('sha256').update(value).digest('hex').slice(0, 20)

package/src/analysis/duplicates.compute.js

@@ -111,7 +111,7 @@ function symbolRanges(graph) {
     if (!line) continue;
     let arr = byFile.get(n.source_file);
     if (!arr) byFile.set(n.source_file, (arr = []));
-    arr.push({ id: n.id, label: n.label || n.id, line });
+    arr.push({ id: n.id, label: n.label || n.id, line, symbolKind: n.symbol_kind || "" });
   }
   for (const arr of byFile.values()) arr.sort((a, b) => a.line - b.line);
   return byFile;
@@ -175,9 +175,14 @@ export function computeDuplicates(repoPath, graphJsonPath, opts = {}) {
       if (end - start < 2) continue;
       const toks = tokenize(stripNonCode(body.join("\n"), py));
       if (toks.strict.length < scanTokenFloor) continue;
+      const strippedBody = stripNonCode(body.join("\n"), py);
+      const declarativeValue = /^(?:export\s+)?(?:const|let|var)\s+[\w$]+(?:\s*:[^=]+)?\s*=\s*(?:Object\.(?:freeze|seal)\s*\(\s*)?[\[{]/s.test(strippedBody.trim())
+        && !/=>|\b(?:function|if|for|while|switch|try|await|yield|return|throw|new)\b/.test(strippedBody);
+      const declarativeFactory = /^(?:export\s+)?const\s+[\w$]+(?:\s*:[^=]+)?\s*=\s*(?:sqliteTable|pgTable|mysqlTable)\s*\(/s.test(strippedBody.trim());
+      const declarative = declarativeValue || declarativeFactory || /^(?:interface|type|enum)$/i.test(syms[i].symbolKind);
       frags.push({
         id: syms[i].id, label: syms[i].label, file, start, end,
-        n: toks.strict.length,
+        n: toks.strict.length, declarative,
         ...classificationFields(pathInfo),
         fp: { strict: fingerprints(toks.strict), renamed: fingerprints(toks.renamed) },
       });

package/src/analysis/health-capabilities.js

@@ -39,6 +39,7 @@ export function buildHealthCapabilityMatrix({
   const noDependencyEvidence = ecosystemRows.length === 0;
   const onlyUnsupportedDependencies = unsupportedDependencyRows.length > 0 && supportedDependencyRows.length === 0;
   const advisorySupported = supportedDependencyRows.some((item) => ["npm", "go", "python", "rust", "maven", "gradle"].includes(item.ecosystem));
+  const onlyRustAdvisories = supportedDependencyRows.length > 0 && supportedDependencyRows.every((item) => item.ecosystem === "rust");
   const malwareSupported = supportedDependencyRows.some((item) => ["npm", "go", "python"].includes(item.ecosystem));
   const coverageSupported = [...languages].some((language) => ["javascript/typescript", "python", "go"].includes(language));
   const runtimeFiles = Number(correctnessCoverage.runtimeCorrectnessFiles || 0);
@@ -71,7 +72,7 @@ export function buildHealthCapabilityMatrix({
     concurrency: concurrencyFiles
       ? capability("CHECKED", "PARTIAL", `Checked ${concurrencyFiles} Java source file(s) for direct InterruptedException restore/rethrow evidence. No race detector ran; race freedom is not claimed.`)
       : capability("NOT_SUPPORTED", "PARTIAL", "No supported Java interruption check applied. No race detector ran; race freedom is not claimed."),
-    advisories: checkCapability(checks.osv, advisorySupported, "OSV advisory matching"),
+    advisories: checkCapability(onlyRustAdvisories && checks.rustsec?.status === "OK" ? checks.rustsec : checks.osv, advisorySupported, onlyRustAdvisories ? "RustSec advisory matching" : "OSV advisory matching"),
     malware: checkCapability(checks.malware, malwareSupported, "Installed-package malware scanning"),
     coverage: measuredCoverageFiles > 0
       ? capability("CHECKED", "COMPLETE", `Mapped an existing supported coverage report to ${measuredCoverageFiles} file(s).`)

package/src/analysis/internal-audit/supply-chain.js

@@ -3,6 +3,7 @@ import { advisoryQueryFingerprint, loadStore, queryStore } from "../../security/
 import { matchAdvisories } from "../../security/match.js";
 import { scanMalware } from "../../security/malware-heuristics.js";
 import { classifyTyposquat } from "../../security/typosquat.js";
+import { loadRustAdvisoryReport } from "../../security/rust-advisory-report.js";
 import { makeFinding } from "../findings.js";
 import { packageReachability } from "../package-reachability.js";
 
@@ -31,8 +32,9 @@ export async function runSupplyChainChecks(repoPath, {
   let installedCount = 0;
   let inst = { installed: [], drift: [] };
   const checks = {
-    osv: { status: "NOT_CHECKED", detail: "Advisory cache was never refreshed for this repository. Enable the osv profile (or advisories capability), then call refresh_advisories explicitly to opt in to sending pinned package names and versions to OSV.dev." },
+    osv: { status: "NOT_CHECKED", detail: "Advisory cache was never refreshed for this repository. The MIT core remains offline; use the separate Weavatrix Online connector only if you choose to query OSV with pinned package names and versions." },
     malware: { status: skipMalwareScan ? "NOT_CHECKED" : "PENDING", detail: skipMalwareScan ? "Installed-package malware scan is opt-in and was not requested." : "" },
+    rustsec: { status: "NOT_CHECKED", detail: "No saved cargo audit --json report was inspected." },
   };
 
   try {
@@ -48,7 +50,7 @@ export async function runSupplyChainChecks(repoPath, {
       const coverage = typeof repoStamp === "object" && Number.isFinite(repoStamp.queried)
         ? ` (${repoStamp.queried_ok ?? repoStamp.queried}/${repoStamp.queried} package versions queried successfully)`
         : "";
-      const drift = fingerprintMatches ? "" : " Dependency versions changed, or this is a legacy stamp without a package fingerprint; enable the osv profile (or advisories capability) and call refresh_advisories for complete coverage.";
+      const drift = fingerprintMatches ? "" : " Dependency versions changed, or this is a legacy stamp without a package fingerprint; refresh through the separate Weavatrix Online connector for complete advisory coverage.";
       checks.osv = {
         status,
         detail: `${status === "PARTIAL" ? "Partially matched" : "Matched"} installed packages against the cached OSV snapshot from ${advisoryDbDate}${coverage}.${drift}`,
@@ -114,6 +116,19 @@ export async function runSupplyChainChecks(repoPath, {
         fixHint: "npm ci (clean install from the lockfile)",
       }));
     }
+    const rustsec = loadRustAdvisoryReport(repoPath);
+    checks.rustsec = { status: rustsec.status, detail: rustsec.detail, checkedAt: rustsec.checkedAt || null };
+    for (const issue of rustsec.findings) {
+      findings.push(makeFinding({
+        category: "vulnerability", rule: issue.kind === "vulnerability" ? "known-vuln" : "rust-advisory-warning",
+        severity: issue.kind === "vulnerability" ? "high" : "medium", confidence: "high",
+        title: `${issue.id}: ${issue.package}${issue.version ? `@${issue.version}` : ""}`,
+        detail: `${issue.title}${issue.patched.length ? ` Patched: ${issue.patched.join(", ")}.` : ""}`,
+        package: issue.package, version: issue.version, source: "rustsec",
+        evidence: issue.url ? [{ file: issue.url, line: 0, snippet: `imported from ${rustsec.file}` }] : [{ file: rustsec.file, line: 0, snippet: issue.id }],
+        fixHint: issue.patched.length ? `upgrade ${issue.package} to a patched RustSec range (${issue.patched.join(", ")})` : `review or replace ${issue.package}; no patched range was reported`,
+      }));
+    }
   } catch (error) {
     checks.osv = { status: "ERROR", detail: `Offline advisory matching failed: ${error instanceof Error ? error.message : String(error)}` };
   }

package/src/analysis/jvm-artifact-index.js

@@ -0,0 +1,87 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const concreteVersion = (value) => !!value && !/[\[\](),${}*+]/.test(String(value));
+const safeEntries = (path) => { try { return readdirSync(path, { withFileTypes: true }); } catch { return []; } };
+
+function findEndOfCentralDirectory(buffer) {
+  const minimum = Math.max(0, buffer.length - 65_557);
+  for (let offset = buffer.length - 22; offset >= minimum; offset--) {
+    if (buffer.readUInt32LE(offset) === 0x06054b50) return offset;
+  }
+  return -1;
+}
+
+// JARs are ZIP files. Reading only the central directory avoids extraction and code execution.
+export function readJarClassNames(path, { maxClasses = 250_000 } = {}) {
+  const buffer = readFileSync(path);
+  const end = findEndOfCentralDirectory(buffer);
+  if (end < 0) throw new Error("ZIP central directory is missing");
+  const entries = buffer.readUInt16LE(end + 10);
+  let offset = buffer.readUInt32LE(end + 16);
+  const classes = new Set(), packages = new Set();
+  let truncated = false;
+  for (let index = 0; index < entries && offset + 46 <= buffer.length; index++) {
+    if (buffer.readUInt32LE(offset) !== 0x02014b50) throw new Error("invalid ZIP central directory entry");
+    const nameLength = buffer.readUInt16LE(offset + 28);
+    const extraLength = buffer.readUInt16LE(offset + 30);
+    const commentLength = buffer.readUInt16LE(offset + 32);
+    let name = buffer.subarray(offset + 46, offset + 46 + nameLength).toString("utf8");
+    offset += 46 + nameLength + extraLength + commentLength;
+    name = name.replace(/^META-INF\/versions\/\d+\//, "");
+    if (!name.endsWith(".class") || /(?:^|\/)(?:module-info|package-info)\.class$/.test(name)) continue;
+    const identity = name.slice(0, -6).replace(/\$/g, ".").replace(/\//g, ".");
+    classes.add(identity);
+    packages.add(identity.includes(".") ? identity.slice(0, identity.lastIndexOf(".")) : "");
+    if (classes.size >= maxClasses) { truncated = true; break; }
+  }
+  return { classes, packages, truncated };
+}
+
+function artifactCandidates(dependency, home) {
+  if (!dependency.group || !dependency.artifact || !concreteVersion(dependency.version)) return [];
+  const file = `${dependency.artifact}-${dependency.version}.jar`;
+  const maven = join(home, ".m2", "repository", ...dependency.group.split("."), dependency.artifact, dependency.version, file);
+  const gradleRoot = join(home, ".gradle", "caches", "modules-2", "files-2.1", dependency.group, dependency.artifact, dependency.version);
+  const gradle = safeEntries(gradleRoot).filter((entry) => entry.isDirectory()).flatMap((entry) =>
+    safeEntries(join(gradleRoot, entry.name)).filter((child) => child.isFile() && child.name.endsWith(".jar"))
+      .map((child) => join(gradleRoot, entry.name, child.name)));
+  return [maven, ...gradle].filter((candidate, index, all) => existsSync(candidate) && all.indexOf(candidate) === index);
+}
+
+const addOwner = (map, key, owner) => {
+  const owners = map.get(key) || new Set();
+  owners.add(owner); map.set(key, owners);
+};
+
+// Exact import -> artifact evidence from already-installed Maven/Gradle JARs. This is offline and
+// read-only: no build tool, plugin, class loader or repository code is executed.
+export function collectJvmArtifactIndex(dependencies, { home = homedir(), maxArtifacts = 256, maxClasses = 500_000 } = {}) {
+  const unique = [...new Map(dependencies.map((dependency) => [dependency.name, dependency])).values()];
+  const classes = new Map(), packages = new Map(), errors = [];
+  let artifactsIndexed = 0, artifactsMissing = 0, classCount = 0, truncated = false;
+  for (const dependency of unique) {
+    if (artifactsIndexed >= maxArtifacts || classCount >= maxClasses) { truncated = true; break; }
+    const candidates = artifactCandidates(dependency, home);
+    if (!candidates.length) { artifactsMissing++; continue; }
+    try {
+      const remaining = Math.max(1, maxClasses - classCount);
+      const content = readJarClassNames(candidates[0], { maxClasses: remaining });
+      for (const identity of content.classes) addOwner(classes, identity, dependency.name);
+      for (const identity of content.packages) addOwner(packages, identity, dependency.name);
+      classCount += content.classes.size; artifactsIndexed++; truncated ||= content.truncated;
+    } catch (error) {
+      errors.push(`${dependency.name}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  const resolve = (spec) => {
+    const imported = String(spec || "").replace(/\.\*$/, "");
+    const owners = String(spec || "").endsWith(".*") ? packages.get(imported) : classes.get(imported);
+    return [...(owners || [])].sort();
+  };
+  return {
+    resolve, artifactsRequired: unique.length, artifactsIndexed, artifactsMissing,
+    classCount, errors, truncated,
+  };
+}

package/src/analysis/jvm-dependency-evidence.js

@@ -1,6 +1,7 @@
 import { createRepoBoundary } from "../repo-path.js";
 import { dependencyVerification, makeFinding } from "./findings.js";
 import { parseGradleDependencies, parseGradleVersionCatalog, parseMavenPom } from "./jvm-manifests.js";
+import { collectJvmArtifactIndex } from "./jvm-artifact-index.js";
 import { listRepoFiles, readRepoText } from "./internal-audit.collect.js";
 
 const normalize = (value) => String(value || "").toLowerCase().replace(/[^a-z0-9]+/g, "");
@@ -24,12 +25,18 @@ function bestDependency(spec, dependencies) {
   return ranked[0].dependency;
 }
 
-function analyze(ecosystem, manifests, dependencies, imports, unresolvedDeclarations, mappingDependencies = dependencies, includeMissing = true) {
+function analyze(ecosystem, manifests, dependencies, imports, unresolvedDeclarations, mappingDependencies = dependencies, includeMissing = true, artifactEvidence) {
   const findings = [], used = new Map(), missing = new Map();
   const owned = new Set(dependencies.map((dependency) => dependency.name));
+  let exactMappedImports = 0, heuristicMappedImports = 0, ambiguousImports = 0;
   for (const item of imports) {
-    const dependency = bestDependency(item.spec || item.pkg, mappingDependencies);
+    const exactOwners = artifactEvidence.resolve(item.spec || item.pkg);
+    if (exactOwners.length > 1) ambiguousImports++;
+    const dependency = exactOwners.length === 1
+      ? mappingDependencies.find((candidate) => candidate.name === exactOwners[0])
+      : bestDependency(item.spec || item.pkg, mappingDependencies);
     if (dependency) {
+      if (exactOwners.length === 1) exactMappedImports++; else heuristicMappedImports++;
       if (owned.has(dependency.name)) {
         const list = used.get(dependency.name) || [];
         list.push(item); used.set(dependency.name, list);
@@ -69,21 +76,36 @@ function analyze(ecosystem, manifests, dependencies, imports, unresolvedDeclarat
     }));
   }
   const present = manifests.length > 0;
+  const exactComplete = present && unresolvedDeclarations === 0 && !artifactEvidence.truncated
+    && artifactEvidence.errors.length === 0 && artifactEvidence.artifactsMissing === 0
+    && artifactEvidence.artifactsIndexed === artifactEvidence.artifactsRequired
+    && exactMappedImports === imports.length && ambiguousImports === 0;
   return {
     present,
     status: present ? "CHECKED" : "NOT_PRESENT",
-    completeness: present ? (unresolvedDeclarations ? "PARTIAL" : "COMPLETE") : "NOT_APPLICABLE",
+    completeness: present ? (exactComplete ? "COMPLETE" : "PARTIAL") : "NOT_APPLICABLE",
     manifests,
     declared: dependencies.length,
     mappedImports: [...used.values()].reduce((sum, list) => sum + list.length, 0),
     unmappedImports: [...missing.values()].reduce((sum, list) => sum + list.length, 0),
     unresolvedDeclarations,
+    exactArtifactEvidence: {
+      artifactsRequired: artifactEvidence.artifactsRequired,
+      artifactsIndexed: artifactEvidence.artifactsIndexed,
+      artifactsMissing: artifactEvidence.artifactsMissing,
+      classesIndexed: artifactEvidence.classCount,
+      exactMappedImports,
+      heuristicMappedImports,
+      ambiguousImports,
+      truncated: artifactEvidence.truncated,
+      errors: artifactEvidence.errors.slice(0, 10),
+    },
     sample: dependencies.slice(0, 20).map(({ file, name, version }) => ({ file, identity: name, version })),
     reason: !present
       ? `No ${ecosystem === "maven" ? "pom.xml" : "Gradle build file"} was discovered.`
-      : unresolvedDeclarations
-        ? `${dependencies.length} declarations and all indexed Java imports were checked, but ${unresolvedDeclarations} dynamic/property/catalog declaration(s) could not be resolved statically.`
-        : `${dependencies.length} declarations were compared with every indexed non-JDK Java import using bounded group-prefix and artifact-token evidence. Missing and unused results remain review evidence, not compiler proof.`,
+      : exactComplete
+        ? `${dependencies.length} declarations were compared with every indexed non-JDK Java import using exact class ownership from ${artifactEvidence.artifactsIndexed} installed JAR(s).`
+        : `${dependencies.length} declarations and every indexed non-JDK Java import were checked, but exact artifact evidence is partial: ${unresolvedDeclarations} unresolved declaration(s), ${artifactEvidence.artifactsMissing} installed JAR(s) missing, ${heuristicMappedImports} heuristic mapping(s), ${ambiguousImports} ambiguous mapping(s). Heuristic missing/unused findings remain review evidence, never compiler proof.`,
     findings,
   };
 }
@@ -108,8 +130,9 @@ export function collectJvmDependencyEvidence(repoRoot, { files = listRepoFiles(r
   });
   const javaImports = externalImports.filter((entry) => entry.ecosystem === "Maven" && entry.pkg && !entry.builtin && !entry.unresolved);
   const allDependencies = [...mavenDependencies, ...gradleDependencies];
+  const artifactEvidence = collectJvmArtifactIndex(allDependencies);
   return {
-    maven: analyze("maven", mavenFiles, mavenDependencies, javaImports, mavenUnresolved, allDependencies, true),
-    gradle: analyze("gradle", [...gradleFiles, ...catalogFiles], gradleDependencies, javaImports, gradleUnresolved, allDependencies, mavenFiles.length === 0),
+    maven: analyze("maven", mavenFiles, mavenDependencies, javaImports, mavenUnresolved, allDependencies, true, artifactEvidence),
+    gradle: analyze("gradle", [...gradleFiles, ...catalogFiles], gradleDependencies, javaImports, gradleUnresolved, allDependencies, mavenFiles.length === 0, artifactEvidence),
   };
 }