@adhisang/minecraft-modding-mcp 6.3.0 → 7.0.0-rc.0

package/dist/source/artifact-resolver.js

@@ -14,6 +14,7 @@ import { resolveTinyRemapperJar } from "../tiny-remapper-resolver.js";
 import { isUnobfuscatedVersion } from "../version-service.js";
 import { dedupeQualityFlags, normalizeMapping, normalizeOptionalString, normalizePathStyle } from "./shared-utils.js";
 const VERSION_TOKEN_REGEX_CACHE = new Map();
+const LOADER_VERSION_TOKEN_REGEX_CACHE = new Map();
 const MAX_HELPER_REGEX_CACHE = 128;
 function rememberCachedRegex(cache, key, regex) {
     if (cache.size >= MAX_HELPER_REGEX_CACHE) {
@@ -57,6 +58,97 @@ export function hasExactVersionToken(path, version) {
         ?? rememberCachedRegex(VERSION_TOKEN_REGEX_CACHE, normalizedVersion, new RegExp(`(^|[^0-9a-z])${escapeRegexLiteral(normalizedVersion)}(?![0-9a-z]|\\.[0-9])`, "i"));
     return pattern.test(normalizedPath);
 }
+/**
+ * True when a path carries the NeoForge/Forge loader version that corresponds
+ * 1:1 to `mcVersion`.
+ *
+ * ModDevGradle names every artifact after the LOADER version and never after
+ * Minecraft: MC 1.21.11 produces `build/moddev/artifacts/neoforge-21.11.38-beta-merged.jar`.
+ * A plain `hasExactVersionToken(path, "1.21.11")` therefore rejected every
+ * artifact of the canonical NeoForge workspace, which made
+ * validate-access-transformer unusable there.
+ *
+ * NeoForge derives its version from Minecraft as `<minor>.<patch>.<build>`, so
+ * `1.21.11` -> `21.11.<build>` and `1.21` -> `21.0.<build>`. The trailing dot
+ * before the build number keeps `21.1.` from matching `21.10.5`.
+ */
+export function hasLoaderRuntimeVersionToken(path, mcVersion) {
+    const match = /^1\.(\d+)(?:\.(\d+))?$/.exec(mcVersion.trim());
+    if (!match) {
+        return false;
+    }
+    const minor = match[1];
+    const patch = match[2] ?? "0";
+    const normalizedPath = normalizePathStyle(path).toLowerCase();
+    const cacheKey = `loader:${minor}.${patch}`;
+    const pattern = LOADER_VERSION_TOKEN_REGEX_CACHE.get(cacheKey)
+        ?? rememberCachedRegex(LOADER_VERSION_TOKEN_REGEX_CACHE, cacheKey, new RegExp(`(^|[^0-9a-z.])${minor}\\.${patch}\\.\\d`, "i"));
+    return pattern.test(normalizedPath);
+}
+const RUNTIME_JAR_VERSION_REGEX = /(?:^|[^0-9.])(1\.\d+(?:\.\d+)?)(?![0-9.])/;
+/**
+ * Minecraft version a runtime jar path carries, or undefined when the path
+ * names none. Loom lays its cache out as
+ * `<gradle>/caches/fabric-loom/<mcVersion>/...`, so the first `1.x[.y]` token
+ * of the path is the version the jar was built for.
+ */
+export function inferRuntimeJarMinecraftVersion(path) {
+    return RUNTIME_JAR_VERSION_REGEX.exec(normalizePathStyle(path))?.[1];
+}
+/**
+ * Loader a runtime jar belongs to, read from its path.
+ *
+ * A Loom cache holds NeoForge-patched jars under a `/neoforge/` segment
+ * (`caches/fabric-loom/1.21.10/neoforge/21.10.50-beta/minecraft-merged-mojang-at-patched.jar`).
+ * Serving one of those to a Fabric workspace silently validated a Fabric access
+ * widener against NeoForge bytecode, so the loader has to travel with the jar.
+ */
+export function inferRuntimeJarLoader(path) {
+    const lower = normalizePathStyle(path).toLowerCase();
+    if (lower.includes("neoforge") || lower.includes("neoform") || lower.includes("moddev")) {
+        return "neoforge";
+    }
+    if (/(^|[/\-_])forge([/\-_.]|$)/.test(lower) || lower.includes("forge_gradle") || lower.includes("srg")) {
+        return "forge";
+    }
+    if (lower.includes("fabric-loom") || lower.includes("loom-cache") || lower.includes("intermediary")) {
+        return "fabric";
+    }
+    return "unknown";
+}
+/**
+ * Fills in the truthful version/loader half of a runtime provenance record.
+ *
+ * `version` becomes the version the SERVED jar carries; the caller's original
+ * request is preserved under `requestedVersion` and flagged. A served loader
+ * that contradicts a KNOWN expected loader is flagged too — never silently
+ * dropped.
+ */
+export function describeServedRuntimeJar(input) {
+    const notes = [];
+    const servedVersion = inferRuntimeJarMinecraftVersion(input.jarPath);
+    const versionApproximated = servedVersion !== undefined && servedVersion !== input.requestedVersion.trim();
+    const servedLoader = inferRuntimeJarLoader(input.jarPath);
+    const expectedLoader = input.expectedLoader;
+    const loaderMismatch = expectedLoader !== undefined &&
+        expectedLoader !== "unknown" &&
+        servedLoader !== "unknown" &&
+        servedLoader !== expectedLoader;
+    if (versionApproximated) {
+        notes.push(`Runtime jar is Minecraft ${servedVersion}, not the requested ${input.requestedVersion}; results are approximate.`);
+    }
+    if (loaderMismatch) {
+        notes.push(`Runtime jar is a ${servedLoader} artifact while the workspace is ${expectedLoader}; its bytecode differs from the ${expectedLoader} runtime.`);
+    }
+    return {
+        version: versionApproximated && servedVersion ? servedVersion : input.requestedVersion,
+        ...(versionApproximated ? { requestedVersion: input.requestedVersion, versionApproximated: true } : {}),
+        servedLoader,
+        ...(expectedLoader ? { expectedLoader } : {}),
+        ...(loaderMismatch ? { loaderMismatch: true } : {}),
+        notes
+    };
+}
 function inferMergedRuntimeNamespaceHint(path) {
     const normalizedPath = normalizePathStyle(path).toLowerCase();
     if (normalizedPath.includes("merged-intermediary-v2") ||
@@ -407,6 +499,11 @@ export async function discoverAccessTransformerRuntimeCandidates(_svc, input) {
     const normalizedProjectPathLower = normalizedProjectPath
         ? normalizePathStyle(normalizedProjectPath).toLowerCase()
         : undefined;
+    // A jar inside the caller's own build directory belongs to the version that
+    // workspace declares, whatever its filename says.
+    const projectAnchorAllowed = normalizedProjectPathLower !== undefined &&
+        input.projectMinecraftVersion !== undefined &&
+        input.projectMinecraftVersion.trim() === input.version.trim();
     const searchRoots = buildLoaderRuntimeSearchRoots({
         projectPath: normalizedProjectPath,
         gradleUserHome: input.gradleUserHome
@@ -449,7 +546,17 @@ export async function discoverAccessTransformerRuntimeCandidates(_svc, input) {
             }
             seen.add(normalizedPath);
             const lower = normalizedPath.toLowerCase();
-            if (!hasExactVersionToken(normalizedPath, input.version)) {
+            const insideProject = normalizedProjectPathLower !== undefined && lower.startsWith(normalizedProjectPathLower);
+            // Positive version evidence is REQUIRED; the three forms are ranked so a
+            // verbatim Minecraft version always beats an inferred one.
+            const versionEvidence = hasExactVersionToken(normalizedPath, input.version)
+                ? "exact-token"
+                : hasLoaderRuntimeVersionToken(normalizedPath, input.version)
+                    ? "loader-token"
+                    : projectAnchorAllowed && insideProject
+                        ? "project-anchored"
+                        : undefined;
+            if (!versionEvidence) {
                 continue;
             }
             const looksMerged = lower.includes("merged");
@@ -457,6 +564,11 @@ export async function discoverAccessTransformerRuntimeCandidates(_svc, input) {
             const looksForge = lower.includes("forge");
             const looksNeoForge = lower.includes("neoforge") || lower.includes("moddev") || lower.includes("neoform");
             const looksPatchedRuntime = lower.includes("patched") || lower.includes("client-extra") || lower.includes("joined");
+            // client-extra / *-minecraft-resources jars carry resources ONLY, so they
+            // can never answer a class lookup. They stay selectable (a workspace that
+            // has nothing else still gets an answer) but must lose to any real
+            // classes jar.
+            const looksResourcesOnly = lower.includes("client-extra") || lower.includes("minecraft-resources");
             const appliedScope = looksMerged
                 ? "merged"
                 : "loader";
@@ -470,18 +582,21 @@ export async function discoverAccessTransformerRuntimeCandidates(_svc, input) {
                 continue;
             }
             const score = 10_000 +
-                (normalizedProjectPathLower && lower.startsWith(normalizedProjectPathLower) ? 4_000 : 0) +
+                (versionEvidence === "exact-token" ? 5_000 : versionEvidence === "loader-token" ? 3_500 : 3_000) +
+                (insideProject ? 4_000 : 0) +
                 (looksPatchedRuntime ? 3_000 : 0) +
                 (looksSrg ? 2_500 : 0) +
                 (input.loader === "forge" && looksForge ? 1_500 : 0) +
                 (input.loader === "neoforge" && looksNeoForge ? 1_500 : 0) +
                 (input.requestedScope === appliedScope ? 1_000 : 0) +
-                (looksMerged ? -500 : 0);
+                (looksMerged ? -500 : 0) +
+                (looksResourcesOnly ? -6_000 : 0);
             candidates.push({
                 jarPath: normalizedPath,
                 score,
                 appliedScope,
-                origin: "local-jar"
+                origin: "local-jar",
+                versionEvidence
             });
         }
     }
@@ -504,6 +619,9 @@ export async function resolveAccessWidenerRuntimeArtifact(svc, input) {
         const detected = await svc.workspaceMappingService.detectProjectMinecraftVersion(normalizedProjectPath);
         version = detected ?? version;
     }
+    const expectedLoader = normalizedProjectPath
+        ? await detectWorkspaceRuntimeLoader(svc, normalizedProjectPath)
+        : undefined;
     const requestedScope = input.scope ?? (normalizedProjectPath ? "loader" : "vanilla");
     if (requestedScope === "vanilla") {
         const versionJar = await svc.versionService.resolveVersionJar(version);
@@ -574,9 +692,21 @@ export async function resolveAccessWidenerRuntimeArtifact(svc, input) {
             notes.push(...detection.warnings);
         }
     }
+    // Provenance must describe the jar that was SERVED, never the request.
+    const served = describeServedRuntimeJar({
+        jarPath: discovery.selected.jarPath,
+        requestedVersion: version,
+        expectedLoader
+    });
+    notes.push(...served.notes);
     return {
-        version,
+        version: served.version,
         jarPath: discovery.selected.jarPath,
+        ...(served.requestedVersion ? { requestedVersion: served.requestedVersion } : {}),
+        ...(served.versionApproximated ? { versionApproximated: true } : {}),
+        servedLoader: served.servedLoader,
+        ...(served.expectedLoader ? { expectedLoader: served.expectedLoader } : {}),
+        ...(served.loaderMismatch ? { loaderMismatch: true } : {}),
         requestedScope,
         appliedScope,
         requestedMapping: input.awNamespace,
@@ -586,6 +716,28 @@ export async function resolveAccessWidenerRuntimeArtifact(svc, input) {
         scopeFallback
     };
 }
+/**
+ * Loader a workspace declares, normalized onto {@link RuntimeLoader}. Quilt is
+ * Fabric-compatible for runtime-jar purposes; anything undetected stays
+ * "unknown" so no mismatch is ever asserted on a guess.
+ */
+async function detectWorkspaceRuntimeLoader(svc, projectPath) {
+    const detection = await svc.workspaceMappingService.detectProjectLoader(projectPath);
+    if (!detection.resolved) {
+        return "unknown";
+    }
+    switch (detection.loader) {
+        case "fabric":
+        case "quilt":
+            return "fabric";
+        case "forge":
+            return "forge";
+        case "neoforge":
+            return "neoforge";
+        default:
+            return "unknown";
+    }
+}
 export async function resolveAccessTransformerNamespace(svc, input) {
     const explicit = normalizeAccessTransformerNamespace(input.atNamespace);
     if (explicit) {
@@ -622,9 +774,15 @@ export async function resolveAccessTransformerNamespace(svc, input) {
 export async function resolveAccessTransformerRuntimeArtifact(svc, input) {
     const normalizedProjectPath = normalizeOptionalProjectPath(input.projectPath);
     let version = input.version;
-    if (input.preferProjectVersion && normalizedProjectPath) {
-        const detected = await svc.workspaceMappingService.detectProjectMinecraftVersion(normalizedProjectPath);
-        version = detected ?? version;
+    // The workspace's own declared version is read whenever a project is given:
+    // preferProjectVersion decides whether it OVERRIDES the requested version,
+    // but discovery needs it either way to anchor project-local artifacts whose
+    // filenames carry only a loader version.
+    const projectMinecraftVersion = normalizedProjectPath
+        ? await svc.workspaceMappingService.detectProjectMinecraftVersion(normalizedProjectPath)
+        : undefined;
+    if (input.preferProjectVersion && projectMinecraftVersion) {
+        version = projectMinecraftVersion;
     }
     const requestedScope = input.scope ?? (normalizedProjectPath ? "loader" : "vanilla");
     if (requestedScope === "vanilla") {
@@ -655,7 +813,8 @@ export async function resolveAccessTransformerRuntimeArtifact(svc, input) {
         gradleUserHome: input.gradleUserHome,
         requestedScope,
         atNamespace: input.atNamespace,
-        loader
+        loader,
+        projectMinecraftVersion
     });
     if (!discovery.selected) {
         throw createError({
@@ -670,7 +829,13 @@ export async function resolveAccessTransformerRuntimeArtifact(svc, input) {
                 candidateArtifacts: discovery.candidateArtifacts,
                 loaderEvidence: loaderDetection.evidence,
                 loaderWarnings: loaderDetection.warnings,
-                nextAction: "Provide projectPath for a Forge/NeoForge workspace with generated runtime jars, or run the Gradle tasks that populate transformed runtime artifacts before retrying."
+                ...(projectMinecraftVersion ? { projectMinecraftVersion } : {}),
+                // An error must never ask for something the caller already sent.
+                nextAction: normalizedProjectPath
+                    ? `Searched the workspace "${normalizedProjectPath}" and the Gradle caches but found no runtime jar for Minecraft ${version}${projectMinecraftVersion && projectMinecraftVersion !== version
+                        ? ` (the workspace declares ${projectMinecraftVersion}; retry with version="${projectMinecraftVersion}" or preferProjectVersion=true)`
+                        : ""}. Run the Gradle task that populates transformed runtime artifacts (NeoForge/ModDevGradle writes them under build/moddev/artifacts), then retry.`
+                    : "Provide projectPath for a Forge/NeoForge workspace with generated runtime jars, or run the Gradle tasks that populate transformed runtime artifacts before retrying."
             }
         });
     }
@@ -690,15 +855,38 @@ export async function resolveAccessTransformerRuntimeArtifact(svc, input) {
                 : "Resolved the closest transformed runtime artifact for validation."
         }
         : undefined;
+    const resolutionNotes = [
+        ...(scopeFallback ? [scopeFallback.reason] : []),
+        ...(selected.versionEvidence && selected.versionEvidence !== "exact-token"
+            ? [
+                selected.versionEvidence === "loader-token"
+                    ? `Runtime jar matched Minecraft ${version} through its loader version token (ModDevGradle names artifacts after the loader, not Minecraft).`
+                    : `Runtime jar matched Minecraft ${version} because it lives in the workspace build directory of a project declaring that version.`
+            ]
+            : [])
+    ];
+    const servedAt = describeServedRuntimeJar({
+        jarPath: selected.jarPath,
+        requestedVersion: version,
+        // An access transformer is a Forge/NeoForge artifact; the workspace loader
+        // refines that when it is known.
+        expectedLoader: loader === "forge" ? "forge" : loader === "neoforge" ? "neoforge" : undefined
+    });
+    resolutionNotes.push(...servedAt.notes);
     return {
-        version,
+        version: servedAt.version,
         jarPath: selected.jarPath,
+        ...(servedAt.requestedVersion ? { requestedVersion: servedAt.requestedVersion } : {}),
+        ...(servedAt.versionApproximated ? { versionApproximated: true } : {}),
+        servedLoader: servedAt.servedLoader,
+        ...(servedAt.expectedLoader ? { expectedLoader: servedAt.expectedLoader } : {}),
+        ...(servedAt.loaderMismatch ? { loaderMismatch: true } : {}),
         requestedScope,
         appliedScope: selected.appliedScope,
         requestedMapping: input.atNamespace,
         mappingApplied,
         origin: selected.origin,
-        resolutionNotes: scopeFallback ? [scopeFallback.reason] : undefined,
+        resolutionNotes: resolutionNotes.length > 0 ? resolutionNotes : undefined,
         scopeFallback
     };
 }
@@ -748,7 +936,7 @@ export async function resolveBinaryFallbackArtifact(svc, input) {
         return undefined;
     }
     try {
-        const fallbackResolved = await resolveSourceTargetInternal({ kind: "jar", value: binaryJarPath }, { allowDecompile: true, preferBinaryOnly: true }, svc.config);
+        const fallbackResolved = await resolveSourceTargetInternal({ kind: "jar", value: binaryJarPath }, { allowDecompile: input.allowDecompile ?? true, preferBinaryOnly: true }, svc.config);
         fallbackResolved.version = fallbackResolved.version ?? input.version;
         fallbackResolved.coordinate = fallbackResolved.coordinate ?? input.coordinate;
         fallbackResolved.requestedMapping = input.requestedMapping;
@@ -1233,7 +1421,20 @@ export async function resolveArtifact(svc, input) {
                     });
                 }
                 resolved.qualityFlags.push("version-approximated");
-                warnings.push(`Requested version "${value}" but resolved source jar does not contain exact version string: ${versionSourceDiscovery.selectedSourceJarPath}`);
+                // Provenance must name the version that was SERVED. Echoing the request
+                // here made a fallback indistinguishable from an exact hit, and left
+                // downstream version context pointing at a version the jar is not.
+                const servedVersion = inferRuntimeJarMinecraftVersion(versionSourceDiscovery.selectedSourceJarPath);
+                provenance.versionApproximation = {
+                    requestedVersion: value,
+                    ...(servedVersion ? { servedVersion } : {}),
+                    sourceJarPath: versionSourceDiscovery.selectedSourceJarPath
+                };
+                if (servedVersion) {
+                    provenance.resolvedFrom.version = servedVersion;
+                }
+                warnings.push(`Requested version "${value}" but resolved source jar does not contain exact version string: ${versionSourceDiscovery.selectedSourceJarPath}` +
+                    (servedVersion ? ` (serving Minecraft ${servedVersion})` : ""));
             }
         }
         resolved.qualityFlags = dedupeQualityFlags(resolved.qualityFlags);

package/dist/source/class-source.d.ts

@@ -40,7 +40,28 @@ export declare function buildFallbackProvenance(svc: SourceService, input: {
 export declare function buildClassSourceNotFoundError(svc: SourceService, input: {
     className: string;
     lookupClassName: string;
+    /**
+     * Artifact the lookup ended on. TWO internal paths move it off the requested
+     * artifact: the binary fallback, and the nested-jar redirect that follows a
+     * shell jar's bundled inner jar.
+     */
     artifactId: string;
+    /**
+     * Artifact the caller actually asked about. Both internal redirects swap the
+     * active artifact mid-lookup, but the error must keep answering about the
+     * requested one: reporting the redirect target sends the caller to an artifact
+     * they never named. Defaults to `artifactId` for paths with no redirect.
+     */
+    requestedArtifactId?: string;
+    /**
+     * Mapping and quality flags OF THE REQUESTED ARTIFACT. `details.artifactId`
+     * names the requested artifact, so `details.mapping` (which reaches
+     * `error.context` through the allowlist) and `details.qualityFlags` have to
+     * describe that same artifact. The nested-jar redirect REPLACES the active
+     * values with the inner jar's, which would otherwise publish one artifact's
+     * identity beside another's namespace and quality — and point the
+     * `suggestedCall` at an index holding neither the class nor its siblings.
+     */
     mappingApplied: SourceMapping;
     requestedMapping: SourceMapping;
     qualityFlags: string[];

package/dist/source/class-source.js

@@ -10,7 +10,7 @@ import { collectDidYouMeanCandidates } from "./did-you-mean.js";
 import { matchesMemberPattern } from "./member-pattern.js";
 import { findNestedJarClasses, resolveUniqueNestedJarForClass } from "./nested-jars.js";
 import { buildPageContextKey, encodeOffsetCursor, resolveCursorOffset } from "../page-cursor.js";
-import { dedupeQualityFlags, normalizeMapping, normalizeOptionalString, normalizePathStyle } from "./shared-utils.js";
+import { dedupeQualityFlags, inheritArtifactMapping, normalizeMapping, normalizeOptionalString, normalizePathStyle } from "./shared-utils.js";
 import { isUnobfuscatedVersion } from "../version-service.js";
 const MEMBERS_STATUS_LEGACY = process.env.MEMBERS_STATUS_LEGACY === "1";
 /**
@@ -175,10 +175,26 @@ export function buildFallbackProvenance(svc, input) {
         transformChain
     };
 }
+/**
+ * Near-miss candidates from the requested artifact's index followed by any the
+ * lookup's final artifact contributes, deduplicated by FQN so a class present in
+ * both is reported once, under the requested artifact.
+ */
+function unionDidYouMeanCandidates(svc, requestedArtifactId, endedOnArtifactId, className) {
+    const requested = collectDidYouMeanCandidates(svc, requestedArtifactId, className);
+    if (endedOnArtifactId === requestedArtifactId) {
+        return requested;
+    }
+    const seen = new Set(requested.map((candidate) => candidate.className));
+    const fromFallback = collectDidYouMeanCandidates(svc, endedOnArtifactId, className, endedOnArtifactId).filter((candidate) => !seen.has(candidate.className));
+    return [...requested, ...fromFallback];
+}
 export function buildClassSourceNotFoundError(svc, input) {
     const simpleName = input.className.split(/[.$]/).at(-1) ?? input.className;
+    const requestedArtifactId = input.requestedArtifactId ?? input.artifactId;
     const details = {
-        artifactId: input.artifactId,
+        artifactId: requestedArtifactId,
+        ...(input.artifactId !== requestedArtifactId ? { fallbackArtifactId: input.artifactId } : {}),
         className: input.className,
         mapping: input.mappingApplied,
         qualityFlags: input.qualityFlags,
@@ -191,12 +207,18 @@ export function buildClassSourceNotFoundError(svc, input) {
         ...(input.nestedJars && input.nestedJars.length > 0 ? { nestedJars: input.nestedJars } : {}),
         // Candidates are hints from the symbol index, never assertions that the
         // class exists at the suggested location; empty when nothing usable.
-        didYouMean: collectDidYouMeanCandidates(svc, input.artifactId, input.className)
+        //
+        // Both indexes are consulted, requested artifact first. Collecting from the
+        // requested artifact ALONE is empty by construction in the scenario the
+        // partial-source fallback exists to serve: that artifact is the one without
+        // net.minecraft symbols, which is why the fallback fired and indexed the other
+        // jar. Candidates from the artifact the caller did not name carry its id.
+        didYouMean: unionDidYouMeanCandidates(svc, requestedArtifactId, input.artifactId, input.className)
     };
     let nextAction = `Use find-class to resolve the correct fully-qualified name for "${simpleName}".`;
     let suggestionSpec = {
         tool: "find-class",
-        params: { className: simpleName, artifactId: input.artifactId }
+        params: { className: simpleName, artifactId: requestedArtifactId }
     };
     if (input.targetKind === "version" && input.scope && input.scope !== "merged" && !input.projectPath) {
         nextAction +=
@@ -225,7 +247,7 @@ export function buildClassSourceNotFoundError(svc, input) {
         else {
             suggestionSpec = {
                 tool: "find-class",
-                params: { className: simpleName, artifactId: input.artifactId }
+                params: { className: simpleName, artifactId: requestedArtifactId }
             };
         }
     }
@@ -403,13 +425,14 @@ export function findClass(svc, input) {
         const filteredMatches = partialVanillaLookup && matches.every((match) => !match.qualifiedName.startsWith("net.minecraft.") && !match.qualifiedName.startsWith("com.mojang."))
             ? []
             : matches;
-        if (filteredMatches.length === 0 && partialVanillaLookup) {
-            warnings.push(`Artifact source coverage is partial and excludes net.minecraft; returning non-vanilla matches for "${className}" would be misleading. Use get-class-source/get-class-members for binary fallback or get-class-api-matrix for mapped API inspection.`);
-        }
-        if (filteredMatches.length === 0 && shouldSuggestObfuscatedMapping(artifact, className)) {
-            warnings.push(`No exact class symbol matched "${className}". ${obfuscatedNamespaceHint(className)}`);
-        }
-        return { matches: filteredMatches, total: filteredMatches.length, warnings };
+        return finishFindClass(svc, {
+            artifact,
+            artifactId,
+            className,
+            matches: filteredMatches,
+            partialVanillaLookup,
+            warnings
+        });
     }
     const result = svc.symbolsRepo.findScopedSymbols({
         artifactId,
@@ -418,32 +441,82 @@ export function findClass(svc, input) {
         symbolKinds: TYPE_SYMBOL_KINDS,
         limit: limit * 5
     });
-    const matches = [];
+    // The extractor stores ONE qualifiedName per FILE (the top-level type), so a
+    // nested type's row carries its OUTER type's FQN. Reporting that verbatim
+    // returned a qualifiedName that did not contain the searched token at all —
+    // feeding match[0] into get-class-source then fetched the wrong class.
+    const candidates = [];
     for (const row of result.items) {
-        if (matches.length >= limit)
-            break;
         const isTypeSymbol = row.symbolKind === "class" || row.symbolKind === "interface" ||
             row.symbolKind === "enum" || row.symbolKind === "record";
         if (!isTypeSymbol)
             continue;
-        matches.push({
-            qualifiedName: row.qualifiedName ?? row.filePath.replace(/\.java$/, "").replaceAll("/", "."),
+        const enclosingQualifiedName = row.qualifiedName ?? row.filePath.replace(/\.java$/, "").replaceAll("/", ".");
+        const enclosingSimpleName = enclosingQualifiedName.split(".").at(-1) ?? enclosingQualifiedName;
+        const nested = enclosingSimpleName !== row.symbolName;
+        candidates.push({
+            qualifiedName: nested ? `${enclosingQualifiedName}.${row.symbolName}` : enclosingQualifiedName,
             filePath: row.filePath,
             line: row.line,
-            symbolKind: row.symbolKind
+            symbolKind: row.symbolKind,
+            ...(nested ? { nested: true, enclosingClass: enclosingQualifiedName } : {})
         });
     }
+    // A top-level type named exactly like the query is what the caller almost
+    // always means; a nested type that merely shares the simple name comes after.
+    candidates.sort((left, right) => {
+        const leftNested = left.nested === true ? 1 : 0;
+        const rightNested = right.nested === true ? 1 : 0;
+        if (leftNested !== rightNested)
+            return leftNested - rightNested;
+        return left.qualifiedName.localeCompare(right.qualifiedName);
+    });
+    const matches = candidates.slice(0, limit);
     const partialVanillaLookup = hasPartialNetMinecraftCoverage(artifact.qualityFlags) && looksLikeDeobfuscatedClassName(className);
     const filteredMatches = partialVanillaLookup && matches.every((match) => !match.qualifiedName.startsWith("net.minecraft.") && !match.qualifiedName.startsWith("com.mojang."))
         ? []
         : matches;
-    if (filteredMatches.length === 0 && partialVanillaLookup) {
+    return finishFindClass(svc, {
+        artifact,
+        artifactId,
+        className,
+        matches: filteredMatches,
+        partialVanillaLookup,
+        warnings
+    });
+}
+/**
+ * Shared tail for both findClass branches: coverage/namespace warnings plus a
+ * machine-usable recovery route.
+ *
+ * An empty result on an artifact whose index excludes net.minecraft is
+ * internally consistent but externally contradictory — get-class-source answers
+ * the SAME class from the binary fallback. The caller therefore gets both the
+ * reason and the exact call that works.
+ */
+function finishFindClass(svc, input) {
+    const { artifact, artifactId, className, matches, partialVanillaLookup, warnings } = input;
+    let suggestedCall;
+    if (matches.length === 0 && partialVanillaLookup) {
         warnings.push(`Artifact source coverage is partial and excludes net.minecraft; returning non-vanilla matches for "${className}" would be misleading. Use get-class-source/get-class-members for binary fallback or get-class-api-matrix for mapped API inspection.`);
+        suggestedCall = buildSuggestedCall({
+            tool: "get-class-source",
+            params: {
+                className,
+                target: { kind: "artifact", artifactId },
+                mode: "metadata"
+            }
+        }).suggestedCall;
     }
-    if (filteredMatches.length === 0 && shouldSuggestObfuscatedMapping(artifact, className)) {
+    if (matches.length === 0 && shouldSuggestObfuscatedMapping(artifact, className)) {
         warnings.push(`No exact class symbol matched "${className}". ${obfuscatedNamespaceHint(className)}`);
     }
-    return { matches: filteredMatches, total: filteredMatches.length, warnings };
+    return {
+        matches,
+        total: matches.length,
+        warnings,
+        ...(suggestedCall ? { suggestedCall } : {})
+    };
 }
 export async function findClassIncludingNested(svc, input) {
     const indexed = findClass(svc, input);
@@ -550,7 +623,7 @@ export async function getClassSource(svc, input) {
         const artifact = svc.getArtifact(artifactId);
         artifactId = artifact.artifactId;
         origin = artifact.origin;
-        requestedMapping = input.mapping != null ? requestedMapping : (artifact.requestedMapping ?? requestedMapping);
+        requestedMapping = inheritArtifactMapping(input.mapping, artifact);
         mappingApplied = artifact.mappingApplied ?? requestedMapping;
         provenance = artifact.provenance;
         qualityFlags = artifact.qualityFlags;
@@ -595,7 +668,11 @@ export async function getClassSource(svc, input) {
             requestedMapping,
             mappingApplied,
             provenance: activeProvenance,
-            qualityFlags: activeQualityFlags
+            qualityFlags: activeQualityFlags,
+            // A caller who declined decompilation must not pay for one here: the
+            // fallback used to hardcode allowDecompile:true and silently ran a full
+            // Vineflower pass on the binary jar.
+            allowDecompile: input.allowDecompile
         });
         if (!fallbackResolved || fallbackResolved.artifactId === activeArtifactId) {
             return false;
@@ -689,11 +766,15 @@ export async function getClassSource(svc, input) {
     if (!filePath) {
         throw buildClassSourceNotFoundError(svc, {
             artifactId: activeArtifactId,
+            requestedArtifactId: artifactId,
             className,
             lookupClassName: activeLookupClassName,
-            mappingApplied: activeMappingApplied,
+            // The REQUESTED artifact's namespace and quality, matching the artifactId this
+            // error reports. The nested-jar redirect replaces the active values with the
+            // inner jar's, which would otherwise describe an artifact the caller never named.
+            mappingApplied,
             requestedMapping,
-            qualityFlags: activeQualityFlags,
+            qualityFlags,
             attemptedBinaryFallback,
             targetKind: input.target?.kind,
             targetValue: input.target && "value" in input.target ? input.target.value : undefined,
@@ -728,11 +809,15 @@ export async function getClassSource(svc, input) {
     if (!row) {
         throw buildClassSourceNotFoundError(svc, {
             artifactId: activeArtifactId,
+            requestedArtifactId: artifactId,
             className,
             lookupClassName: activeLookupClassName,
-            mappingApplied: activeMappingApplied,
+            // The REQUESTED artifact's namespace and quality, matching the artifactId this
+            // error reports. The nested-jar redirect replaces the active values with the
+            // inner jar's, which would otherwise describe an artifact the caller never named.
+            mappingApplied,
             requestedMapping,
-            qualityFlags: activeQualityFlags,
+            qualityFlags,
             attemptedBinaryFallback,
             filePath,
             targetKind: input.target?.kind,
@@ -910,6 +995,7 @@ export async function getClassMembers(svc, input) {
         const artifact = svc.getArtifact(artifactId);
         artifactId = artifact.artifactId;
         origin = artifact.origin;
+        requestedMapping = inheritArtifactMapping(input.mapping, artifact);
         mappingApplied = artifact.mappingApplied ?? requestedMapping;
         provenance = artifact.provenance;
         qualityFlags = artifact.qualityFlags;
@@ -1179,7 +1265,18 @@ export async function getClassMembers(svc, input) {
         truncated,
         ...(nextCursor ? { nextCursor } : {}),
         ...(memberCursorIgnored ? { cursorIgnored: true } : {}),
-        context: signatureContext,
+        context: {
+            ...signatureContext,
+            // The jar-derived context describes the BYTECODE the reader opened. The
+            // members handed back have already been remapped into requestedMapping,
+            // so echoing the jar namespace here contradicted `returnedNamespace` in
+            // the same payload. Report what the response actually contains, and fill
+            // the version the resolver established when the jar path yielded none.
+            ...(signatureContext.minecraftVersion === "unknown" && version
+                ? { minecraftVersion: version }
+                : {}),
+            mappingNamespace: requestedMapping
+        },
         origin,
         artifactId,
         requestedMapping,