@adhisang/minecraft-modding-mcp 1.1.0 → 1.2.0

package/dist/source-service.js

@@ -1,4 +1,9 @@
 import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, resolve as resolvePath } from "node:path";
+import fastGlob from "fast-glob";
 import { createError, ERROR_CODES, isAppError } from "./errors.js";
 import { loadConfig } from "./config.js";
 import { decompileBinaryJar } from "./decompiler/vineflower.js";
@@ -12,7 +17,7 @@ import { resolveSourceTarget as resolveSourceTargetInternal } from "./source-res
 import { applyMappingPipeline } from "./mapping-pipeline-service.js";
 import { MappingService } from "./mapping-service.js";
 import { extractSymbolsFromSource } from "./symbols/symbol-extractor.js";
-import { iterateJavaEntriesAsUtf8 } from "./source-jar-reader.js";
+import { iterateJavaEntriesAsUtf8, listJavaEntries } from "./source-jar-reader.js";
 import { openDatabase } from "./storage/db.js";
 import { ArtifactsRepo } from "./storage/artifacts-repo.js";
 import { FilesRepo } from "./storage/files-repo.js";
@@ -20,6 +25,7 @@ import { IndexMetaRepo } from "./storage/index-meta-repo.js";
 import { SymbolsRepo } from "./storage/symbols-repo.js";
 import { RuntimeMetrics } from "./observability.js";
 import { log } from "./logger.js";
+import { normalizePathForHost } from "./path-converter.js";
 import { createSearchHitAccumulator, decodeSearchCursor, encodeSearchCursor } from "./search-hit-accumulator.js";
 import { WorkspaceMappingService } from "./workspace-mapping-service.js";
 import { VersionService, isUnobfuscatedVersion } from "./version-service.js";
@@ -27,6 +33,24 @@ import { RegistryService } from "./registry-service.js";
 import { VersionDiffService } from "./version-diff-service.js";
 import { ModDecompileService } from "./mod-decompile-service.js";
 import { ModSearchService } from "./mod-search-service.js";
+const utf8Decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+function truncateUtf8ToMaxBytes(content, maxBytes) {
+    const encoded = Buffer.from(content, "utf8");
+    if (encoded.length <= maxBytes) {
+        return content;
+    }
+    let end = Math.max(0, Math.min(maxBytes, encoded.length));
+    while (end > 0) {
+        try {
+            const decoded = utf8Decoder.decode(encoded.subarray(0, end));
+            return decoded;
+        }
+        catch {
+            end -= 1;
+        }
+    }
+    return "";
+}
 const INDEX_SCHEMA_VERSION = 1;
 const SYMBOL_KINDS = ["class", "interface", "enum", "record", "method", "field"];
 function isSymbolKind(value) {
@@ -43,6 +67,43 @@ const MAX_REGEX_RESULT_LIMIT = 100;
 function normalizePathStyle(path) {
     return path.replaceAll("\\", "/");
 }
+function escapeRegexLiteral(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function hasExactVersionToken(path, version) {
+    const normalizedPath = normalizePathStyle(path).toLowerCase();
+    const normalizedVersion = version.trim().toLowerCase();
+    if (!normalizedVersion) {
+        return false;
+    }
+    // Avoid prefix false-positives like "1.21.1" matching "1.21.10".
+    const pattern = new RegExp(`(^|[^0-9a-z])${escapeRegexLiteral(normalizedVersion)}([^0-9a-z]|$)`, "i");
+    return pattern.test(normalizedPath);
+}
+function normalizeOptionalProjectPath(projectPath) {
+    if (!projectPath) {
+        return undefined;
+    }
+    const trimmed = projectPath.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    const normalized = normalizePathForHost(trimmed, undefined, "projectPath");
+    return isAbsolute(normalized) ? normalized : resolvePath(process.cwd(), normalized);
+}
+function buildVersionSourceSearchRoots(projectPath) {
+    const roots = new Set();
+    if (projectPath) {
+        roots.add(resolvePath(projectPath, ".gradle", "loom-cache"));
+        roots.add(resolvePath(projectPath, ".gradle-user", "caches", "fabric-loom"));
+        roots.add(resolvePath(projectPath, ".gradle", "caches", "fabric-loom"));
+        return [...roots];
+    }
+    const homeGradle = resolvePath(homedir(), ".gradle");
+    roots.add(resolvePath(homeGradle, "loom-cache"));
+    roots.add(resolvePath(homeGradle, "caches", "fabric-loom"));
+    return [...roots];
+}
 function parseQualifiedMethodSymbol(symbol) {
     const trimmed = symbol.trim();
     const separator = trimmed.lastIndexOf(".");
@@ -91,6 +152,20 @@ function normalizeStrictPositiveInt(value, field) {
     }
     return value;
 }
+const COMMON_SOURCE_ROOTS = [
+    "src/main/java",
+    "src/client/java",
+    "common/src/main/java",
+    "common/src/client/java",
+    "fabric/src/main/java",
+    "fabric/src/client/java",
+    "neoforge/src/main/java",
+    "neoforge/src/client/java",
+    "forge/src/main/java",
+    "forge/src/client/java",
+    "quilt/src/main/java",
+    "quilt/src/client/java"
+];
 function normalizeMapping(mapping) {
     if (mapping == null) {
         return "official";
@@ -104,7 +179,11 @@ function normalizeMapping(mapping) {
     throw createError({
         code: ERROR_CODES.MAPPING_UNAVAILABLE,
         message: `Unsupported mapping "${mapping}".`,
-        details: { mapping }
+        details: {
+            mapping,
+            nextAction: "Try mapping=official which is always available.",
+            suggestedCall: { tool: "resolve-artifact", params: { mapping: "official" } }
+        }
     });
 }
 function normalizeAccessWidenerNamespace(namespace) {
@@ -258,11 +337,33 @@ function canUseIndexedSearchPath(indexedSearchEnabled, intent, match, _scope) {
     return true;
 }
 function buildGlobRegex(pattern) {
-    const escaped = pattern
-        .replace(/[-/\\^$+?.()|[\]{}]/g, "\\$&")
-        .replace(/\\\*/g, ".*")
-        .replace(/\\\?/g, ".");
-    return new RegExp(`^${escaped}$`);
+    const REGEX_META = /[-/\\^$+.()|[\]{}]/;
+    let result = "";
+    let i = 0;
+    while (i < pattern.length) {
+        const ch = pattern[i];
+        if (ch === "*" && pattern[i + 1] === "*") {
+            result += ".*";
+            i += 2;
+            if (pattern[i] === "/") {
+                result += "(?:/)?";
+                i += 1;
+            }
+        }
+        else if (ch === "*") {
+            result += "[^/]*";
+            i += 1;
+        }
+        else if (ch === "?") {
+            result += "[^/]";
+            i += 1;
+        }
+        else {
+            result += REGEX_META.test(ch) ? `\\${ch}` : ch;
+            i += 1;
+        }
+    }
+    return new RegExp(`^${result}$`);
 }
 function globToSqlLike(pattern) {
     let result = "";
@@ -283,6 +384,27 @@ function globToSqlLike(pattern) {
     }
     return result;
 }
+function isPackageCompatible(filePath, classPath) {
+    const lastSlash = classPath.lastIndexOf("/");
+    if (lastSlash < 0)
+        return true;
+    const expectedPrefix = classPath.slice(0, lastSlash + 1);
+    return filePath.startsWith(expectedPrefix);
+}
+function classNameToClassPath(className) {
+    const normalized = normalizePathStyle(className.trim()).replace(/\//g, ".");
+    const segments = normalized.split(".").filter((segment) => segment.length > 0);
+    if (segments.length === 0) {
+        return "";
+    }
+    const firstTypeSegment = segments.findIndex((segment) => /^[A-Z_$]/.test(segment));
+    if (firstTypeSegment < 0) {
+        return segments.join("/");
+    }
+    const packagePath = segments.slice(0, firstTypeSegment).join("/");
+    const typePath = segments.slice(firstTypeSegment).join("$");
+    return packagePath ? `${packagePath}/${typePath}` : typePath;
+}
 function checkPackagePrefix(filePath, packagePrefix) {
     if (!packagePrefix) {
         return true;
@@ -304,6 +426,7 @@ function buildSearchCursorContext(input) {
         query: input.query,
         intent: input.intent,
         match: input.match,
+        queryMode: input.queryMode,
         includeDefinition: input.includeDefinition,
         packagePrefix: input.scope?.packagePrefix ?? "",
         fileGlob: input.scope?.fileGlob ?? "",
@@ -479,11 +602,95 @@ export class SourceService {
         this.symbolsRepo = new SymbolsRepo(this.db);
         this.refreshCacheMetrics();
     }
+    async discoverVersionSourceJar(input) {
+        const normalizedProjectPath = normalizeOptionalProjectPath(input.projectPath);
+        const searchRoots = buildVersionSourceSearchRoots(normalizedProjectPath);
+        const searchedPaths = [];
+        const candidates = [];
+        const seen = new Set();
+        for (const root of searchRoots) {
+            searchedPaths.push(root);
+            let discovered = [];
+            try {
+                discovered = fastGlob.sync("**/*sources.jar", {
+                    cwd: root,
+                    absolute: true,
+                    onlyFiles: true
+                });
+            }
+            catch {
+                continue;
+            }
+            for (const candidatePath of discovered) {
+                const normalizedPath = normalizePathStyle(candidatePath);
+                if (seen.has(normalizedPath)) {
+                    continue;
+                }
+                seen.add(normalizedPath);
+                const lower = normalizedPath.toLowerCase();
+                if (!lower.includes(input.version.toLowerCase()) && !lower.includes("minecraft")) {
+                    continue;
+                }
+                let javaEntries = [];
+                try {
+                    javaEntries = await listJavaEntries(normalizedPath);
+                }
+                catch {
+                    continue;
+                }
+                if (javaEntries.length === 0) {
+                    continue;
+                }
+                const hasMinecraftNamespace = javaEntries.some((entry) => normalizePathStyle(entry).startsWith("net/minecraft/"));
+                const score = (hasMinecraftNamespace ? 10_000 : 0) +
+                    (lower.includes("minecraft-merged") ? 2_000 : 0) +
+                    (lower.includes(input.version.toLowerCase()) ? 1_000 : 0) +
+                    Math.min(javaEntries.length, 500);
+                candidates.push({
+                    jarPath: normalizedPath,
+                    javaEntryCount: javaEntries.length,
+                    hasMinecraftNamespace,
+                    score
+                });
+            }
+        }
+        candidates.sort((left, right) => {
+            if (right.score !== left.score) {
+                return right.score - left.score;
+            }
+            return left.jarPath.localeCompare(right.jarPath);
+        });
+        const selected = candidates.find((candidate) => candidate.hasMinecraftNamespace) ?? candidates[0];
+        const candidateArtifacts = candidates
+            .slice(0, 20)
+            .map((candidate) => `${candidate.jarPath}#java=${candidate.javaEntryCount}`);
+        return {
+            searchedPaths,
+            candidateArtifacts,
+            selectedSourceJarPath: selected?.jarPath
+        };
+    }
+    buildVersionSourceRecoveryCommand(projectPath) {
+        const normalizedProjectPath = normalizeOptionalProjectPath(projectPath);
+        const prefix = normalizedProjectPath
+            ? `cd ${JSON.stringify(normalizedProjectPath)} && `
+            : "";
+        return `${prefix}./gradlew genSources --no-daemon`;
+    }
     async resolveArtifact(input) {
         const kind = input.target.kind;
-        const value = input.target.value?.trim();
+        let value = input.target.value?.trim();
         const mapping = normalizeMapping(input.mapping);
+        const scope = input.scope;
         const warnings = [];
+        // P5: preferProjectVersion - detect MC version from gradle.properties
+        if (input.preferProjectVersion && input.projectPath && kind === "version") {
+            const detected = await this.workspaceMappingService.detectProjectMinecraftVersion(input.projectPath);
+            if (detected && detected !== value) {
+                warnings.push(`Overriding version "${value}" with project version "${detected}" from gradle.properties.`);
+            }
+            value = detected ?? value;
+        }
         if (!value) {
             throw createError({
                 code: ERROR_CODES.INVALID_INPUT,
@@ -509,6 +716,7 @@ export class SourceService {
         try {
             let resolvedTarget = { kind, value };
             let resolvedVersion;
+            let versionSourceDiscovery;
             if (kind === "version") {
                 const versionJar = await this.versionService.resolveVersionJar(value);
                 resolvedVersion = versionJar.version;
@@ -534,6 +742,19 @@ export class SourceService {
                 warnings.push(`Version ${resolvedVersion} is unobfuscated; ${mapping} mappings are not applicable. Using official names.`);
                 effectiveMapping = "official";
             }
+            if (kind === "version" && resolvedVersion && effectiveMapping === "mojang" && scope !== "vanilla") {
+                versionSourceDiscovery = await this.discoverVersionSourceJar({
+                    version: resolvedVersion,
+                    projectPath: input.projectPath
+                });
+                if (versionSourceDiscovery.selectedSourceJarPath) {
+                    resolvedTarget = {
+                        kind: "jar",
+                        value: versionSourceDiscovery.selectedSourceJarPath
+                    };
+                    warnings.push(`Resolved source-backed artifact from Loom cache candidate: ${versionSourceDiscovery.selectedSourceJarPath}.`);
+                }
+            }
             const resolved = await resolveSourceTargetInternal(resolvedTarget, {
                 // mojang requires source-backed artifact guarantee; force resolution to consider decompile candidate
                 // and reject later if mapping cannot be applied.
@@ -551,11 +772,59 @@ export class SourceService {
                 }
             }, this.config);
             resolved.version = resolvedVersion;
-            const mappingDecision = applyMappingPipeline({
-                requestedMapping: effectiveMapping,
-                target: { kind, value },
-                resolved
-            });
+            let mappingDecision;
+            try {
+                mappingDecision = applyMappingPipeline({
+                    requestedMapping: effectiveMapping,
+                    target: { kind, value },
+                    resolved
+                });
+            }
+            catch (caughtError) {
+                if (isAppError(caughtError) && caughtError.code === ERROR_CODES.MAPPING_NOT_APPLIED) {
+                    const isVanillaMojang = scope === "vanilla" && effectiveMapping === "mojang";
+                    let suggestedCall;
+                    let nextAction;
+                    if (isVanillaMojang && input.projectPath) {
+                        suggestedCall = {
+                            tool: "resolve-artifact",
+                            params: { targetKind: kind, targetValue: value, mapping: "mojang", scope: "merged", projectPath: input.projectPath }
+                        };
+                        nextAction =
+                            "scope=vanilla blocks Loom cache discovery needed for mojang mapping. " +
+                                "Retry with scope=merged to allow source-jar resolution from the project cache.";
+                    }
+                    else if (isVanillaMojang) {
+                        suggestedCall = {
+                            tool: "resolve-artifact",
+                            params: { targetKind: kind, targetValue: value, mapping: "official", scope: "vanilla" }
+                        };
+                        nextAction =
+                            "scope=vanilla blocks Loom cache discovery needed for mojang mapping. " +
+                                "Without a projectPath, use mapping=official to read vanilla obfuscated names.";
+                    }
+                    else {
+                        suggestedCall = {
+                            tool: "resolve-artifact",
+                            params: { targetKind: kind, targetValue: value, mapping: "official", ...(scope ? { scope } : {}) }
+                        };
+                        nextAction = "Retry with mapping=official to use obfuscated names.";
+                    }
+                    throw createError({
+                        code: ERROR_CODES.MAPPING_NOT_APPLIED,
+                        message: caughtError.message,
+                        details: {
+                            ...(caughtError.details ?? {}),
+                            searchedPaths: versionSourceDiscovery?.searchedPaths ?? [],
+                            candidateArtifacts: versionSourceDiscovery?.candidateArtifacts ?? resolved.adjacentSourceCandidates ?? [],
+                            recommendedCommand: this.buildVersionSourceRecoveryCommand(input.projectPath),
+                            nextAction,
+                            suggestedCall
+                        }
+                    });
+                }
+                throw caughtError;
+            }
             const additionalTransformChain = [];
             if (effectiveMapping === "intermediary" || effectiveMapping === "yarn") {
                 if (!resolved.version) {
@@ -565,7 +834,8 @@ export class SourceService {
                         details: {
                             mapping: effectiveMapping,
                             target: { kind, value },
-                            nextAction: "Use targetKind=version or a versioned Maven coordinate so mapping artifacts can be resolved."
+                            nextAction: "Use targetKind=version or a versioned Maven coordinate so mapping artifacts can be resolved.",
+                            suggestedCall: { tool: "resolve-artifact", params: { targetKind: "version", targetValue: value, ...(scope ? { scope } : {}) } }
                         }
                     });
                 }
@@ -588,8 +858,46 @@ export class SourceService {
             resolved.requestedMapping = effectiveMapping;
             resolved.mappingApplied = mappingDecision.mappingApplied;
             resolved.provenance = provenance;
-            resolved.qualityFlags = mappingDecision.qualityFlags;
+            resolved.qualityFlags = [...mappingDecision.qualityFlags];
+            if (versionSourceDiscovery?.candidateArtifacts.length) {
+                resolved.qualityFlags.push("source-jar-found");
+            }
+            if (versionSourceDiscovery?.selectedSourceJarPath) {
+                resolved.qualityFlags.push("source-jar-validated");
+                if (kind === "version" && !hasExactVersionToken(versionSourceDiscovery.selectedSourceJarPath, value)) {
+                    if (input.strictVersion) {
+                        throw createError({
+                            code: ERROR_CODES.VERSION_NOT_FOUND,
+                            message: `Strict version match failed: requested "${value}" but nearest source jar is for a different version.`,
+                            details: {
+                                requestedVersion: value,
+                                selectedSourceJar: versionSourceDiscovery.selectedSourceJarPath,
+                                candidateArtifacts: versionSourceDiscovery.candidateArtifacts,
+                                nextAction: "Use strictVersion=false (default) to allow approximation, or ensure the exact version source jar is in the Loom cache.",
+                                suggestedCall: { tool: "resolve-artifact", params: { targetKind: "version", targetValue: value, strictVersion: false } }
+                            }
+                        });
+                    }
+                    resolved.qualityFlags.push("version-approximated");
+                    warnings.push(`Requested version "${value}" but resolved source jar does not contain exact version string: ${versionSourceDiscovery.selectedSourceJarPath}`);
+                }
+            }
+            resolved.qualityFlags = [...new Set(resolved.qualityFlags)];
             await this.ingestIfNeeded(resolved);
+            let sampleEntries;
+            if (resolved.sourceJarPath) {
+                try {
+                    const javaEntries = await listJavaEntries(resolved.sourceJarPath);
+                    const MAX_SAMPLE = 10;
+                    sampleEntries = javaEntries.slice(0, MAX_SAMPLE);
+                    if (javaEntries.length > MAX_SAMPLE) {
+                        sampleEntries.push(`... and ${javaEntries.length - MAX_SAMPLE} more .java entries`);
+                    }
+                }
+                catch {
+                    // non-fatal: sampleEntries remains undefined
+                }
+            }
             return {
                 artifactId: resolved.artifactId,
                 origin: resolved.origin,
@@ -602,9 +910,10 @@ export class SourceService {
                 requestedMapping: effectiveMapping,
                 mappingApplied: mappingDecision.mappingApplied,
                 provenance,
-                qualityFlags: mappingDecision.qualityFlags,
+                qualityFlags: resolved.qualityFlags,
                 repoUrl: resolved.repoUrl,
-                warnings
+                warnings,
+                sampleEntries
             };
         }
         catch (caughtError) {
@@ -658,11 +967,13 @@ export class SourceService {
             const snippetWindow = buildSnippetWindow(input.include?.snippetLines);
             const regexPattern = match === "regex" ? compileRegex(query) : undefined;
             const scope = input.scope;
+            const queryMode = input.queryMode ?? "auto";
             const cursorContext = buildSearchCursorContext({
                 artifactId: artifact.artifactId,
                 query,
                 intent,
                 match,
+                queryMode,
                 scope,
                 includeDefinition
             });
@@ -677,6 +988,8 @@ export class SourceService {
             const recordHit = (hit) => {
                 accumulator.add(hit);
             };
+            const hasSeparators = /[._$]/.test(query);
+            const tokenOnlyTextIntent = intent === "text" && queryMode === "token";
             if (intent === "symbol") {
                 this.searchSymbolIntent(artifact.artifactId, query, match, scope, snippetWindow, regexPattern, recordHit);
                 // WS4: Use repo-level COUNT for symbol totalApprox when not regex
@@ -691,14 +1004,21 @@ export class SourceService {
                     accumulator.setTotalApproxOverride(approxCount);
                 }
             }
+            else if (queryMode === "literal" && intent === "text") {
+                // F-03: queryMode=literal forces substring scan for text intent
+                this.metrics.recordSearchFallback();
+                this.searchTextIntent(artifact.artifactId, query, match, scope, includeDefinition, snippetWindow, regexPattern, recordHit);
+            }
             else if (!indexedSearchEnabled) {
                 this.metrics.recordIndexedDisabled();
-                this.metrics.recordSearchFallback();
-                if (intent === "path") {
-                    this.searchPathIntent(artifact.artifactId, query, match, scope, includeDefinition, snippetWindow, regexPattern, recordHit);
-                }
-                else {
-                    this.searchTextIntent(artifact.artifactId, query, match, scope, includeDefinition, snippetWindow, regexPattern, recordHit);
+                if (!tokenOnlyTextIntent) {
+                    this.metrics.recordSearchFallback();
+                    if (intent === "path") {
+                        this.searchPathIntent(artifact.artifactId, query, match, scope, includeDefinition, snippetWindow, regexPattern, recordHit);
+                    }
+                    else {
+                        this.searchTextIntent(artifact.artifactId, query, match, scope, includeDefinition, snippetWindow, regexPattern, recordHit);
+                    }
                 }
             }
             else if (canUseIndexedSearchPath(indexedSearchEnabled, intent, match, scope)) {
@@ -714,6 +1034,10 @@ export class SourceService {
                         // WS4: Use repo-level COUNT for totalApprox instead of accumulator count
                         const approxCount = this.filesRepo.countTextCandidates(artifact.artifactId, query);
                         accumulator.setTotalApproxOverride(approxCount);
+                        // F-03: queryMode=auto fallback — when indexed returns 0 hits and query has separators, retry with literal scan
+                        if (queryMode === "auto" && hasSeparators && accumulator.currentCount() === 0) {
+                            this.searchTextIntent(artifact.artifactId, query, match, scope, includeDefinition, snippetWindow, regexPattern, recordHit);
+                        }
                     }
                     this.metrics.recordSearchIndexedHit();
                 }
@@ -725,6 +1049,20 @@ export class SourceService {
                         match,
                         reason: caughtError instanceof Error ? caughtError.message : String(caughtError)
                     });
+                    // F-03: queryMode=token suppresses error-path fallback to brute-force scan
+                    if (!tokenOnlyTextIntent) {
+                        if (intent === "path") {
+                            this.searchPathIntent(artifact.artifactId, query, match, scope, includeDefinition, snippetWindow, regexPattern, recordHit);
+                        }
+                        else {
+                            this.searchTextIntent(artifact.artifactId, query, match, scope, includeDefinition, snippetWindow, regexPattern, recordHit);
+                        }
+                    }
+                }
+            }
+            else {
+                if (!tokenOnlyTextIntent) {
+                    this.metrics.recordSearchFallback();
                     if (intent === "path") {
                         this.searchPathIntent(artifact.artifactId, query, match, scope, includeDefinition, snippetWindow, regexPattern, recordHit);
                     }
@@ -733,15 +1071,6 @@ export class SourceService {
                     }
                 }
             }
-            else {
-                this.metrics.recordSearchFallback();
-                if (intent === "path") {
-                    this.searchPathIntent(artifact.artifactId, query, match, scope, includeDefinition, snippetWindow, regexPattern, recordHit);
-                }
-                else {
-                    this.searchTextIntent(artifact.artifactId, query, match, scope, includeDefinition, snippetWindow, regexPattern, recordHit);
-                }
-            }
             this.metrics.recordSearchIntentDuration(intent, Date.now() - intentStartedAt);
             const finalizedHits = accumulator.finalize();
             const page = finalizedHits.page;
@@ -765,11 +1094,14 @@ export class SourceService {
                 this.metrics.recordOneHopExpansion(relations.length);
             }
             this.metrics.recordSearchTokenBytesReturned(Buffer.byteLength(JSON.stringify({ hits: page, relations }), "utf8"));
+            // B5: If post-filtering eliminated all hits on the first page, the SQL-based
+            // totalApprox is misleading — correct it to 0.
+            const totalApprox = page.length === 0 && !cursor ? 0 : finalizedHits.totalApprox;
             return {
                 hits: page,
                 relations: relations && relations.length > 0 ? relations : undefined,
                 nextCursor,
-                totalApprox: finalizedHits.totalApprox,
+                totalApprox,
                 mappingApplied: artifact.mappingApplied ?? "official"
             };
         }
@@ -792,9 +1124,7 @@ export class SourceService {
             const maxBytes = clampLimit(input.maxBytes, this.config.maxContentBytes, Number.MAX_SAFE_INTEGER);
             const fullBytes = Buffer.byteLength(row.content, "utf8");
             const truncated = fullBytes > maxBytes;
-            const content = truncated
-                ? Buffer.from(row.content, "utf8").slice(0, maxBytes).toString("utf8")
-                : row.content;
+            const content = truncated ? truncateUtf8ToMaxBytes(row.content, maxBytes) : row.content;
             if (truncated) {
                 log("warn", "source.get_file.truncated", {
                     artifactId: input.artifactId,
@@ -1090,7 +1420,11 @@ export class SourceService {
             throw createError({
                 code: ERROR_CODES.VERSION_NOT_FOUND,
                 message: "No Minecraft versions were returned by manifest.",
-                details: { includeSnapshots }
+                details: {
+                    includeSnapshots,
+                    nextAction: "Use list-versions to see available Minecraft versions.",
+                    suggestedCall: { tool: "list-versions", params: {} }
+                }
             });
         }
         const chronological = [...manifestOrder].reverse();
@@ -1102,14 +1436,22 @@ export class SourceService {
             throw createError({
                 code: ERROR_CODES.VERSION_NOT_FOUND,
                 message: `fromVersion "${requestedFrom}" was not found in manifest.`,
-                details: { fromVersion: requestedFrom }
+                details: {
+                    fromVersion: requestedFrom,
+                    nextAction: "Use list-versions to see available Minecraft versions.",
+                    suggestedCall: { tool: "list-versions", params: {} }
+                }
             });
         }
         if (toIndex < 0) {
             throw createError({
                 code: ERROR_CODES.VERSION_NOT_FOUND,
                 message: `toVersion "${requestedTo}" was not found in manifest.`,
-                details: { toVersion: requestedTo }
+                details: {
+                    toVersion: requestedTo,
+                    nextAction: "Use list-versions to see available Minecraft versions.",
+                    suggestedCall: { tool: "list-versions", params: {} }
+                }
             });
         }
         if (fromIndex > toIndex) {
@@ -1248,7 +1590,11 @@ export class SourceService {
         if (manifestOrder.length === 0) {
             throw createError({
                 code: ERROR_CODES.VERSION_NOT_FOUND,
-                message: "No Minecraft versions were returned by manifest."
+                message: "No Minecraft versions were returned by manifest.",
+                details: {
+                    nextAction: "Use list-versions to see available Minecraft versions.",
+                    suggestedCall: { tool: "list-versions", params: {} }
+                }
             });
         }
         const chronological = [...manifestOrder].reverse();
@@ -1258,14 +1604,22 @@ export class SourceService {
             throw createError({
                 code: ERROR_CODES.VERSION_NOT_FOUND,
                 message: `fromVersion "${fromVersion}" was not found in manifest.`,
-                details: { fromVersion }
+                details: {
+                    fromVersion,
+                    nextAction: "Use list-versions to see available Minecraft versions.",
+                    suggestedCall: { tool: "list-versions", params: {} }
+                }
             });
         }
         if (toIndex < 0) {
             throw createError({
                 code: ERROR_CODES.VERSION_NOT_FOUND,
                 message: `toVersion "${toVersion}" was not found in manifest.`,
-                details: { toVersion }
+                details: {
+                    toVersion,
+                    nextAction: "Use list-versions to see available Minecraft versions.",
+                    suggestedCall: { tool: "list-versions", params: {} }
+                }
             });
         }
         if (fromIndex > toIndex) {
@@ -1388,18 +1742,18 @@ export class SourceService {
                     : diffMembersByKey(fromMembers.fields, toMembers.fields, (member) => member.name, true);
         // Remap diff delta members for non-official mappings
         const remapDelta = async (delta, kind) => {
-            const [remappedAdded, remappedRemoved] = await Promise.all([
+            const [addedResult, removedResult] = await Promise.all([
                 this.remapSignatureMembers(delta.added, kind, toVersion, mapping, input.sourcePriority, warnings),
                 this.remapSignatureMembers(delta.removed, kind, fromVersion, mapping, input.sourcePriority, warnings)
             ]);
             const remappedModified = await Promise.all(delta.modified.map(async (change) => {
-                const [fromArr, toArr] = await Promise.all([
+                const [fromResult, toResult] = await Promise.all([
                     this.remapSignatureMembers([change.from], kind, fromVersion, mapping, input.sourcePriority, warnings),
                     this.remapSignatureMembers([change.to], kind, toVersion, mapping, input.sourcePriority, warnings)
                 ]);
-                return { ...change, from: fromArr[0], to: toArr[0] };
+                return { ...change, from: fromResult.members[0], to: toResult.members[0] };
             }));
-            return { added: remappedAdded, removed: remappedRemoved, modified: remappedModified };
+            return { added: addedResult.members, removed: removedResult.members, modified: remappedModified };
         };
         const [remappedConstructors, remappedMethods, remappedFields] = await Promise.all([
             remapDelta(constructors, "method"),
@@ -1447,6 +1801,78 @@ export class SourceService {
             warnings
         };
     }
+    findClass(input) {
+        const className = input.className.trim();
+        if (!className) {
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: "className must be non-empty."
+            });
+        }
+        const artifactId = input.artifactId.trim();
+        if (!artifactId) {
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: "artifactId must be non-empty."
+            });
+        }
+        // Verify artifact exists
+        this.getArtifact(artifactId);
+        const limit = Math.max(1, Math.min(input.limit ?? 20, 200));
+        const warnings = [];
+        const isQualified = className.includes(".");
+        if (isQualified) {
+            // Qualified name: fetch a broad candidate set first, then filter to exact class path/FQCN.
+            // Limiting before filtering can miss the target when many packages share the same simple name.
+            const classPath = className.replace(/\./g, "/");
+            const result = this.symbolsRepo.findScopedSymbols({
+                artifactId,
+                query: className.split(".").at(-1) ?? className,
+                match: "exact",
+                limit: 5000
+            });
+            const matches = result.items
+                .filter((row) => {
+                const isTypeSymbol = row.symbolKind === "class" || row.symbolKind === "interface" ||
+                    row.symbolKind === "enum" || row.symbolKind === "record";
+                if (!isTypeSymbol)
+                    return false;
+                const rowQualified = row.qualifiedName ?? row.filePath.replace(/\.java$/, "").replaceAll("/", ".");
+                return rowQualified === className || row.filePath === `${classPath}.java`;
+            })
+                .map((row) => ({
+                qualifiedName: row.qualifiedName ?? row.filePath.replace(/\.java$/, "").replaceAll("/", "."),
+                filePath: row.filePath,
+                line: row.line,
+                symbolKind: row.symbolKind
+            }))
+                .slice(0, limit);
+            return { matches, total: matches.length, warnings };
+        }
+        // Simple name: search for exact symbol name match among type symbols
+        const result = this.symbolsRepo.findScopedSymbols({
+            artifactId,
+            query: className,
+            match: "exact",
+            limit: limit * 5 // over-fetch to filter by kind
+        });
+        const matches = [];
+        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("/", "."),
+                filePath: row.filePath,
+                line: row.line,
+                symbolKind: row.symbolKind
+            });
+        }
+        return { matches, total: matches.length, warnings };
+    }
     async getClassSource(input) {
         const className = input.className.trim();
         if (!className) {
@@ -1455,9 +1881,16 @@ export class SourceService {
                 message: "className must be non-empty."
             });
         }
+        const mode = input.mode ?? "metadata";
         const startLine = normalizeStrictPositiveInt(input.startLine, "startLine");
         const endLine = normalizeStrictPositiveInt(input.endLine, "endLine");
-        const maxLines = normalizeStrictPositiveInt(input.maxLines, "maxLines");
+        let maxLines = normalizeStrictPositiveInt(input.maxLines, "maxLines");
+        const maxChars = normalizeStrictPositiveInt(input.maxChars, "maxChars");
+        const outputFile = normalizeOptionalString(input.outputFile);
+        // In snippet mode, default maxLines to 200 when no range or maxLines is specified
+        if (mode === "snippet" && startLine == null && endLine == null && maxLines == null) {
+            maxLines = 200;
+        }
         if (startLine != null && endLine != null && startLine > endLine) {
             throw createError({
                 code: ERROR_CODES.INVALID_LINE_RANGE,
@@ -1497,7 +1930,11 @@ export class SourceService {
                 target: input.target,
                 mapping: input.mapping,
                 sourcePriority: input.sourcePriority,
-                allowDecompile: input.allowDecompile
+                allowDecompile: input.allowDecompile,
+                projectPath: input.projectPath,
+                scope: input.scope,
+                preferProjectVersion: input.preferProjectVersion,
+                strictVersion: input.strictVersion
             });
             artifactId = resolved.artifactId;
             origin = resolved.origin;
@@ -1517,41 +1954,100 @@ export class SourceService {
         }
         const filePath = this.resolveClassFilePath(artifactId, className);
         if (!filePath) {
+            const simpleName = className.split(/[.$]/).at(-1) ?? className;
+            const targetKind = input.target?.kind;
+            const targetValue = input.target?.value;
+            const scope = input.scope;
+            let nextAction = `Use find-class to resolve the correct fully-qualified name for "${simpleName}".`;
+            if (targetKind === "version" && scope && scope !== "merged" && !input.projectPath) {
+                nextAction +=
+                    ` If the class exists in a modded environment, retry with scope: "merged" and projectPath pointing to your mod project.`;
+            }
+            else if (targetKind === "version" && scope && scope !== "merged" && input.projectPath) {
+                nextAction +=
+                    ` The class may exist in merged sources; retry with scope: "merged".`;
+            }
             throw createError({
                 code: ERROR_CODES.CLASS_NOT_FOUND,
                 message: `Source for class "${className}" was not found.`,
                 details: {
                     artifactId,
-                    className
+                    className,
+                    ...(scope ? { scope } : {}),
+                    ...(targetKind ? { targetKind } : {}),
+                    ...(targetValue ? { targetValue } : {}),
+                    mapping: mappingApplied,
+                    nextAction,
+                    suggestedCall: { tool: "find-class", params: { className: simpleName, artifactId } }
                 }
             });
         }
         const row = this.filesRepo.getFileContent(artifactId, filePath);
         if (!row) {
+            const simpleName = className.split(/[.$]/).at(-1) ?? className;
             throw createError({
                 code: ERROR_CODES.CLASS_NOT_FOUND,
                 message: `Source for class "${className}" was not found.`,
                 details: {
                     artifactId,
                     className,
-                    filePath
+                    filePath,
+                    ...(input.scope ? { scope: input.scope } : {}),
+                    ...(input.target?.kind ? { targetKind: input.target.kind } : {}),
+                    ...(input.target?.value ? { targetValue: input.target.value } : {}),
+                    nextAction: `Use find-class to resolve the correct fully-qualified name for "${simpleName}".`,
+                    suggestedCall: { tool: "find-class", params: { className: simpleName, artifactId } }
                 }
             });
         }
         const lines = row.content.split(/\r?\n/);
         const totalLines = lines.length;
-        const requestedStart = startLine ?? 1;
-        const requestedEnd = endLine ?? totalLines;
-        const normalizedStart = Math.min(Math.max(1, requestedStart), Math.max(totalLines, 1));
-        const normalizedEnd = Math.min(Math.max(normalizedStart, requestedEnd), Math.max(totalLines, 1));
-        let selectedLines = lines.slice(normalizedStart - 1, normalizedEnd);
-        const clippedByRange = normalizedStart !== requestedStart || normalizedEnd !== requestedEnd;
-        let clippedByMax = false;
-        if (maxLines != null && selectedLines.length > maxLines) {
-            selectedLines = selectedLines.slice(0, maxLines);
-            clippedByMax = true;
-        }
-        const returnedEnd = normalizedStart + Math.max(0, selectedLines.length - 1);
+        let sourceText;
+        let returnedStart;
+        let returnedEnd;
+        let truncated = false;
+        let charsTruncated = false;
+        if (mode === "metadata") {
+            const metadataText = this.extractClassMetadata(filePath, row.content);
+            sourceText = metadataText;
+            returnedStart = 1;
+            returnedEnd = totalLines;
+            truncated = false;
+        }
+        else {
+            // snippet and full modes use the existing line-range logic
+            const requestedStart = startLine ?? 1;
+            const requestedEnd = endLine ?? totalLines;
+            const normalizedStart = Math.min(Math.max(1, requestedStart), Math.max(totalLines, 1));
+            const normalizedEnd = Math.min(Math.max(normalizedStart, requestedEnd), Math.max(totalLines, 1));
+            let selectedLines = lines.slice(normalizedStart - 1, normalizedEnd);
+            const clippedByRange = normalizedStart !== requestedStart || normalizedEnd !== requestedEnd;
+            let clippedByMax = false;
+            if (maxLines != null && selectedLines.length > maxLines) {
+                selectedLines = selectedLines.slice(0, maxLines);
+                clippedByMax = true;
+            }
+            sourceText = selectedLines.join("\n");
+            returnedStart = normalizedStart;
+            returnedEnd = normalizedStart + Math.max(0, selectedLines.length - 1);
+            truncated = clippedByRange || clippedByMax;
+        }
+        // Apply maxChars truncation
+        if (maxChars != null && sourceText.length > maxChars) {
+            sourceText = sourceText.slice(0, maxChars);
+            charsTruncated = true;
+            truncated = true;
+        }
+        // Write to file if outputFile is specified
+        let resolvedOutputFile;
+        if (outputFile) {
+            const outputPath = isAbsolute(outputFile)
+                ? outputFile
+                : resolvePath(outputFile);
+            await writeFile(outputPath, sourceText, "utf8");
+            resolvedOutputFile = outputPath;
+            sourceText = `[Written to ${outputPath}]`;
+        }
         const normalizedProvenance = provenance ??
             this.buildFallbackProvenance({
                 artifactId,
@@ -1561,19 +2057,22 @@ export class SourceService {
             });
         return {
             className,
-            sourceText: selectedLines.join("\n"),
+            mode,
+            sourceText,
             totalLines,
             returnedRange: {
-                start: normalizedStart,
+                start: returnedStart,
                 end: returnedEnd
             },
-            truncated: clippedByRange || clippedByMax,
+            truncated,
+            ...(charsTruncated ? { charsTruncated } : {}),
             origin,
             artifactId,
             requestedMapping,
             mappingApplied,
             provenance: normalizedProvenance,
             qualityFlags,
+            ...(resolvedOutputFile ? { outputFile: resolvedOutputFile } : {}),
             warnings
         };
     }
@@ -1625,7 +2124,11 @@ export class SourceService {
                 target: input.target,
                 mapping: requestedMapping,
                 sourcePriority: input.sourcePriority,
-                allowDecompile: input.allowDecompile
+                allowDecompile: input.allowDecompile,
+                projectPath: input.projectPath,
+                scope: input.scope,
+                preferProjectVersion: input.preferProjectVersion,
+                strictVersion: input.strictVersion
             });
             artifactId = resolved.artifactId;
             origin = resolved.origin;
@@ -1651,7 +2154,8 @@ export class SourceService {
                 message: `Non-official mapping "${requestedMapping}" requires a version, but none was resolved.`,
                 details: {
                     mapping: requestedMapping,
-                    nextAction: "Resolve with targetKind=version or specify a versioned coordinate."
+                    nextAction: "Resolve with targetKind=version or specify a versioned coordinate.",
+                    suggestedCall: { tool: "resolve-artifact", params: { targetKind: "version", targetValue: "latest" } }
                 }
             });
         }
@@ -1679,13 +2183,13 @@ export class SourceService {
         });
         warnings.push(...signature.warnings);
         let remappedConstructors = version != null
-            ? await this.remapSignatureMembers(signature.constructors, "method", version, requestedMapping, input.sourcePriority, warnings)
+            ? (await this.remapSignatureMembers(signature.constructors, "method", version, requestedMapping, input.sourcePriority, warnings)).members
             : signature.constructors;
         let remappedFields = version != null
-            ? await this.remapSignatureMembers(signature.fields, "field", version, requestedMapping, input.sourcePriority, warnings)
+            ? (await this.remapSignatureMembers(signature.fields, "field", version, requestedMapping, input.sourcePriority, warnings)).members
             : signature.fields;
         let remappedMethods = version != null
-            ? await this.remapSignatureMembers(signature.methods, "method", version, requestedMapping, input.sourcePriority, warnings)
+            ? (await this.remapSignatureMembers(signature.methods, "method", version, requestedMapping, input.sourcePriority, warnings)).members
             : signature.methods;
         // Apply memberPattern post-remap for non-official mappings
         if (requestedMapping !== "official" && memberPattern) {
@@ -1744,40 +2248,272 @@ export class SourceService {
         };
     }
     async validateMixin(input) {
-        const version = input.version.trim();
+        // Mixin config mode: read JSON config(s) and derive sourcePaths
+        if (input.mixinConfigPath) {
+            const configPaths = Array.isArray(input.mixinConfigPath) ? input.mixinConfigPath : [input.mixinConfigPath];
+            const allSourcePaths = [];
+            for (const rawConfigPath of configPaths) {
+                const normalizedConfigPath = normalizePathForHost(rawConfigPath, undefined, "mixinConfigPath");
+                const resolvedConfigPath = isAbsolute(normalizedConfigPath)
+                    ? normalizedConfigPath
+                    : resolvePath(process.cwd(), normalizedConfigPath);
+                let configJson;
+                try {
+                    const raw = await readFile(resolvedConfigPath, "utf-8");
+                    configJson = JSON.parse(raw);
+                }
+                catch (err) {
+                    throw createError({
+                        code: ERROR_CODES.INVALID_INPUT,
+                        message: `Could not read/parse mixinConfigPath "${rawConfigPath}": ${err instanceof Error ? err.message : String(err)}`
+                    });
+                }
+                const pkg = configJson.package ?? "";
+                const classNames = [
+                    ...(configJson.mixins ?? []),
+                    ...(configJson.client ?? []),
+                    ...(configJson.server ?? [])
+                ];
+                if (classNames.length === 0) {
+                    continue; // Skip empty configs in array mode
+                }
+                // Determine source root(s)
+                const projectBase = input.projectPath
+                    ? (isAbsolute(input.projectPath) ? input.projectPath : resolvePath(process.cwd(), input.projectPath))
+                    : dirname(resolvedConfigPath);
+                let sourceRootCandidates;
+                if (input.sourceRoots && input.sourceRoots.length > 0) {
+                    sourceRootCandidates = input.sourceRoots;
+                }
+                else if (input.sourceRoot) {
+                    sourceRootCandidates = [input.sourceRoot];
+                }
+                else {
+                    // Auto-detect: include any root that contains at least one configured mixin class.
+                    const detected = COMMON_SOURCE_ROOTS.filter((candidateRoot) => classNames.some((className) => {
+                        const fqcn = pkg ? `${pkg}.${className}` : className;
+                        const relative = fqcn.replace(/\./g, "/") + ".java";
+                        return existsSync(resolvePath(projectBase, candidateRoot, relative));
+                    }));
+                    if (detected.length > 0) {
+                        sourceRootCandidates = detected;
+                    }
+                    else {
+                        sourceRootCandidates = ["src/main/java"];
+                    }
+                }
+                // Build sourcePaths by probing each class against candidate roots
+                for (const cls of classNames) {
+                    const fqcn = pkg ? `${pkg}.${cls}` : cls;
+                    const relativePath = fqcn.replace(/\./g, "/") + ".java";
+                    let found = false;
+                    for (const root of sourceRootCandidates) {
+                        const candidate = resolvePath(projectBase, root, relativePath);
+                        if (existsSync(candidate)) {
+                            allSourcePaths.push(candidate);
+                            found = true;
+                            break;
+                        }
+                    }
+                    if (!found) {
+                        // Fallback to first root for error reporting
+                        allSourcePaths.push(resolvePath(projectBase, sourceRootCandidates[0], relativePath));
+                    }
+                }
+            }
+            if (allSourcePaths.length === 0) {
+                throw createError({
+                    code: ERROR_CODES.INVALID_INPUT,
+                    message: `Mixin config(s) contain no mixin class entries.`
+                });
+            }
+            return this.validateMixinBatch({ ...input, mixinConfigPath: undefined, sourcePaths: allSourcePaths });
+        }
+        // Batch mode: delegate to validateMixinBatch when sourcePaths is provided
+        if (input.sourcePaths && input.sourcePaths.length > 0) {
+            return this.validateMixinBatch(input);
+        }
+        let version = input.version.trim();
         if (!version) {
             throw createError({ code: ERROR_CODES.INVALID_INPUT, message: "version must be non-empty." });
         }
-        const source = input.source;
+        // Resolve source from source or sourcePath
+        let source;
+        if (input.sourcePath) {
+            const normalizedSourcePath = normalizePathForHost(input.sourcePath, undefined, "sourcePath");
+            const resolvedSourcePath = isAbsolute(normalizedSourcePath)
+                ? normalizedSourcePath
+                : resolvePath(process.cwd(), normalizedSourcePath);
+            try {
+                source = await readFile(resolvedSourcePath, "utf-8");
+            }
+            catch (err) {
+                throw createError({
+                    code: ERROR_CODES.INVALID_INPUT,
+                    message: `Could not read sourcePath "${input.sourcePath}" (resolved to "${resolvedSourcePath}"):` +
+                        ` ${err instanceof Error ? err.message : String(err)}`
+                });
+            }
+        }
+        else {
+            source = input.source ?? "";
+        }
         if (!source.trim()) {
             throw createError({ code: ERROR_CODES.INVALID_INPUT, message: "source must be non-empty." });
         }
         const warnings = [];
-        const requestedMapping = normalizeMapping(input.mapping);
-        const { jarPath } = await this.versionService.resolveVersionJar(version);
+        let mappingAutoDetected = false;
+        // Auto-detect mapping from project config when not explicitly provided (or when preferProjectMapping is set)
+        let detectedMapping;
+        if ((!input.mapping || input.preferProjectMapping) && input.projectPath) {
+            try {
+                const detection = await this.workspaceMappingService.detectCompileMapping({ projectPath: input.projectPath });
+                if (detection.resolved && detection.mappingApplied) {
+                    detectedMapping = detection.mappingApplied;
+                    mappingAutoDetected = true;
+                    warnings.push(`Auto-detected mapping '${detectedMapping}' from project configuration.`);
+                    warnings.push(...detection.warnings);
+                }
+                else {
+                    warnings.push(...detection.warnings);
+                }
+            }
+            catch {
+                // Detection failed — fall through to default
+            }
+        }
+        const requestedMapping = normalizeMapping(detectedMapping ?? input.mapping);
+        let mappingApplied = requestedMapping;
+        // preferProjectVersion: detect MC version from gradle.properties
+        if (input.preferProjectVersion && input.projectPath) {
+            const detected = await this.workspaceMappingService.detectProjectMinecraftVersion(input.projectPath);
+            if (detected && detected !== version) {
+                warnings.push(`Overriding version "${version}" with project version "${detected}" from gradle.properties.`);
+            }
+            version = detected ?? version;
+        }
+        // Resolve jar: use Loom cache for non-vanilla scope with projectPath
+        let jarPath;
+        let scopeFallback;
+        if (input.scope && input.scope !== "vanilla" && input.projectPath) {
+            try {
+                const resolved = await this.resolveArtifact({
+                    target: { kind: "version", value: version },
+                    mapping: requestedMapping,
+                    sourcePriority: input.sourcePriority,
+                    projectPath: input.projectPath,
+                    scope: input.scope,
+                    preferProjectVersion: false
+                });
+                jarPath = resolved.binaryJarPath ?? (await this.versionService.resolveVersionJar(version)).jarPath;
+                warnings.push(...resolved.warnings);
+                mappingApplied = resolved.mappingApplied;
+                if (resolved.version) {
+                    version = resolved.version;
+                }
+            }
+            catch (scopeErr) {
+                // Scope preflight failed — fall back to vanilla
+                scopeFallback = {
+                    requested: input.scope,
+                    applied: "vanilla",
+                    reason: `Loom cache unavailable: ${scopeErr instanceof Error ? scopeErr.message : String(scopeErr)}`
+                };
+                warnings.push(`Scope "${input.scope}" resolution failed; falling back to vanilla. ${scopeFallback.reason}`);
+                jarPath = (await this.versionService.resolveVersionJar(version)).jarPath;
+            }
+        }
+        else {
+            jarPath = (await this.versionService.resolveVersionJar(version)).jarPath;
+        }
+        // Guard: reject sources jars — they contain Java source, not bytecode
+        if (jarPath.includes("-sources.jar")) {
+            warnings.push(`Resolved jar appears to be a sources jar. Falling back to vanilla client jar.`);
+            jarPath = (await this.versionService.resolveVersionJar(version)).jarPath;
+            scopeFallback = {
+                requested: input.scope ?? "vanilla",
+                applied: "vanilla",
+                reason: "Resolved jar was a sources jar, not a binary class jar."
+            };
+        }
+        // Health check: probe mapping infrastructure
+        let healthReport;
+        try {
+            const health = await this.mappingService.checkMappingHealth({
+                version,
+                requestedMapping,
+                sourcePriority: input.sourcePriority
+            });
+            const jarAvailable = existsSync(jarPath);
+            healthReport = {
+                jarAvailable,
+                jarPath,
+                mojangMappingsAvailable: health.mojangMappingsAvailable,
+                tinyMappingsAvailable: health.tinyMappingsAvailable,
+                memberRemapAvailable: health.memberRemapAvailable,
+                overallHealthy: jarAvailable && health.mojangMappingsAvailable,
+                degradations: [
+                    ...(jarAvailable ? [] : ["Game jar not found."]),
+                    ...health.degradations
+                ]
+            };
+        }
+        catch {
+            // Health check failed — proceed without it
+        }
         const parsed = parseMixinSource(source);
         const targetMembers = new Map();
+        const mappingFailedTargets = new Set();
+        const remapFailedMembers = new Map();
+        const signatureFailedTargets = new Set();
+        const symbolExistsButSignatureFailed = new Set();
+        const resolutionTrace = input.explain ? [] : undefined;
         for (const target of parsed.targets) {
-            let officialName = target.className;
+            // Bug 1 fix: resolve simple names via imports
+            let resolvedClassName = target.className;
+            if (!resolvedClassName.includes(".")) {
+                // Simple name — look up in imports
+                const fqcn = parsed.imports.get(resolvedClassName);
+                if (fqcn) {
+                    resolvedClassName = fqcn;
+                }
+            }
+            else {
+                // Might be inner class like Foo.Bar where Foo is imported
+                const segments = resolvedClassName.split(".");
+                const firstSegment = segments[0];
+                if (firstSegment && /^[A-Z]/.test(firstSegment)) {
+                    const outerFqcn = parsed.imports.get(firstSegment);
+                    if (outerFqcn) {
+                        resolvedClassName = outerFqcn + "$" + segments.slice(1).join("$");
+                    }
+                }
+            }
+            let officialName = resolvedClassName;
             if (requestedMapping !== "official") {
                 try {
                     const mapped = await this.mappingService.findMapping({
                         version,
                         kind: "class",
-                        name: target.className,
+                        name: resolvedClassName,
                         sourceMapping: requestedMapping,
                         targetMapping: "official",
                         sourcePriority: input.sourcePriority
                     });
                     if (mapped.resolved && mapped.resolvedSymbol) {
                         officialName = mapped.resolvedSymbol.name;
+                        resolutionTrace?.push({ target: target.className, step: "mapping", input: resolvedClassName, output: officialName, success: true });
                     }
                     else {
-                        warnings.push(`Could not map class "${target.className}" from ${requestedMapping} to official.`);
+                        warnings.push(`Could not map class "${resolvedClassName}" from ${requestedMapping} to official; using "${officialName}" for lookup.`);
+                        mappingFailedTargets.add(target.className);
+                        resolutionTrace?.push({ target: target.className, step: "mapping", input: resolvedClassName, output: officialName, success: false, detail: "No mapping found" });
                     }
                 }
-                catch {
-                    warnings.push(`Mapping lookup failed for class "${target.className}".`);
+                catch (mapErr) {
+                    warnings.push(`Mapping lookup failed for class "${resolvedClassName}"; using "${officialName}" for lookup.`);
+                    mappingFailedTargets.add(target.className);
+                    resolutionTrace?.push({ target: target.className, step: "mapping", input: resolvedClassName, output: officialName, success: false, detail: mapErr instanceof Error ? mapErr.message : String(mapErr) });
                 }
             }
             try {
@@ -1787,18 +2523,288 @@ export class SourceService {
                     access: "all"
                 });
                 warnings.push(...sig.warnings);
+                resolutionTrace?.push({ target: target.className, step: "signature", input: officialName, output: `${sig.methods.length} methods, ${sig.fields.length} fields`, success: true });
+                // Bug 2 fix: remap signature members to requested mapping
+                let constructors = sig.constructors;
+                let methods = sig.methods;
+                let fields = sig.fields;
+                if (requestedMapping !== "official") {
+                    try {
+                        const [ctorResult, methodResult, fieldResult] = await Promise.all([
+                            this.remapSignatureMembers(sig.constructors, "method", version, requestedMapping, input.sourcePriority, warnings),
+                            this.remapSignatureMembers(sig.methods, "method", version, requestedMapping, input.sourcePriority, warnings),
+                            this.remapSignatureMembers(sig.fields, "field", version, requestedMapping, input.sourcePriority, warnings)
+                        ]);
+                        constructors = ctorResult.members;
+                        methods = methodResult.members;
+                        fields = fieldResult.members;
+                        // Collect remap-failed member names for this target
+                        const targetFailed = new Set();
+                        for (const n of ctorResult.failedNames)
+                            targetFailed.add(n);
+                        for (const n of methodResult.failedNames)
+                            targetFailed.add(n);
+                        for (const n of fieldResult.failedNames)
+                            targetFailed.add(n);
+                        if (targetFailed.size > 0) {
+                            remapFailedMembers.set(target.className, targetFailed);
+                            resolutionTrace?.push({ target: target.className, step: "remap", input: `${targetFailed.size} members`, output: "failed", success: false });
+                        }
+                        else {
+                            resolutionTrace?.push({ target: target.className, step: "remap", input: `${methods.length + fields.length} members`, output: "remapped", success: true });
+                        }
+                    }
+                    catch (remapErr) {
+                        warnings.push(`Member remapping failed for "${resolvedClassName}"; falling back to official names. Member names shown may be in official (obfuscated) namespace.`);
+                        mappingApplied = "official";
+                        resolutionTrace?.push({ target: target.className, step: "remap", input: resolvedClassName, output: "official fallback", success: false, detail: remapErr instanceof Error ? remapErr.message : String(remapErr) });
+                    }
+                }
                 targetMembers.set(target.className, {
                     className: target.className,
-                    constructors: sig.constructors,
-                    methods: sig.methods,
-                    fields: sig.fields
+                    constructors,
+                    methods,
+                    fields
                 });
             }
-            catch {
-                warnings.push(`Could not load signature for class "${officialName}".`);
+            catch (sigErr) {
+                warnings.push(`Could not load signature for class "${resolvedClassName}" (official: "${officialName}").`);
+                signatureFailedTargets.add(target.className);
+                resolutionTrace?.push({ target: target.className, step: "signature", input: officialName, output: "CLASS_NOT_FOUND", success: false, detail: sigErr instanceof Error ? sigErr.message : String(sigErr) });
+                // Fallback: check if the symbol exists in the mapping graph even though getSignature failed
+                try {
+                    const existenceCheck = await this.mappingService.checkSymbolExists({
+                        version, kind: "class", name: resolvedClassName,
+                        sourceMapping: requestedMapping, nameMode: "auto"
+                    });
+                    if (existenceCheck.resolved) {
+                        signatureFailedTargets.delete(target.className);
+                        symbolExistsButSignatureFailed.add(target.className);
+                        resolutionTrace?.push({ target: target.className, step: "fallback-check", input: resolvedClassName, output: "exists in mapping graph", success: true });
+                    }
+                    else {
+                        resolutionTrace?.push({ target: target.className, step: "fallback-check", input: resolvedClassName, output: "not found", success: false });
+                    }
+                }
+                catch {
+                    // Fallback check failed — keep as signatureFailedTarget
+                    resolutionTrace?.push({ target: target.className, step: "fallback-check", input: resolvedClassName, output: "check failed", success: false });
+                }
+            }
+        }
+        // Fix toolHealth accuracy: reflect actual failures after target resolution
+        if (healthReport) {
+            const hasFailures = signatureFailedTargets.size > 0 || mappingFailedTargets.size > 0;
+            if (hasFailures && healthReport.overallHealthy) {
+                healthReport.overallHealthy = false;
+                healthReport.degradations.push(`${mappingFailedTargets.size} mapping failure(s), ${signatureFailedTargets.size} signature failure(s).`);
+            }
+        }
+        const resolutionNotes = [];
+        if (requestedMapping !== mappingApplied) {
+            resolutionNotes.push(`Mapping fallback: requested "${requestedMapping}" but applied "${mappingApplied}" due to remapping failure.`);
+        }
+        // Count remap failures from warnings
+        const REMAP_WARNING_RE = /^(?:Could not remap|Remap failed for)\b/;
+        const remapFailures = warnings.filter((w) => REMAP_WARNING_RE.test(w)).length;
+        // Determine confidence level
+        let confidence = "definite";
+        if (requestedMapping !== mappingApplied) {
+            confidence = "uncertain";
+        }
+        else if (remapFailures > 0) {
+            confidence = "likely";
+        }
+        // Build mapping chain description
+        const mappingChain = [];
+        if (requestedMapping !== "official") {
+            mappingChain.push(`${requestedMapping} → official`);
+            if (mappingApplied !== requestedMapping) {
+                mappingChain.push(`fallback to ${mappingApplied}`);
             }
         }
-        return validateParsedMixin(parsed, targetMembers, warnings);
+        const provenance = {
+            version,
+            jarPath,
+            requestedMapping,
+            mappingApplied,
+            resolutionNotes: resolutionNotes.length > 0 ? resolutionNotes : undefined,
+            jarType: scopeFallback ? "vanilla-client" : (input.scope && input.scope !== "vanilla" && input.projectPath) ? "merged" : "vanilla-client",
+            mappingChain: mappingChain.length > 0 ? mappingChain : undefined,
+            remapFailures: remapFailures > 0 ? remapFailures : undefined,
+            mappingAutoDetected: mappingAutoDetected || undefined,
+            scopeFallback,
+            resolutionTrace: resolutionTrace && resolutionTrace.length > 0 ? resolutionTrace : undefined
+        };
+        const result = validateParsedMixin(parsed, targetMembers, warnings, provenance, confidence, mappingFailedTargets, input.explain, remapFailedMembers, signatureFailedTargets, input.explain ? { scope: input.scope, sourcePriority: input.sourcePriority, projectPath: input.projectPath, mapping: requestedMapping } : undefined, input.warningMode, healthReport, symbolExistsButSignatureFailed.size > 0 ? symbolExistsButSignatureFailed : undefined);
+        // Apply minSeverity / hideUncertain filters
+        const minSeverity = input.minSeverity ?? "all";
+        const hideUncertain = input.hideUncertain ?? false;
+        if (minSeverity !== "all" || hideUncertain) {
+            const unfilteredSummary = { ...result.summary };
+            let filtered = result.issues;
+            if (minSeverity === "error") {
+                filtered = filtered.filter((i) => i.severity === "error");
+            }
+            else if (minSeverity === "warning") {
+                filtered = filtered.filter((i) => i.severity === "error" || i.severity === "warning");
+            }
+            if (hideUncertain) {
+                filtered = filtered.filter((i) => i.confidence !== "uncertain");
+            }
+            const filteredErrors = filtered.filter((i) => i.severity === "error").length;
+            const filteredWarnings = filtered.filter((i) => i.severity === "warning").length;
+            const filteredDefiniteErrors = filtered.filter((i) => i.severity === "error" && i.confidence !== "uncertain").length;
+            const filteredUncertainErrors = filtered.filter((i) => i.severity === "error" && i.confidence === "uncertain").length;
+            const filteredResolutionErrors = filtered.filter((i) => i.resolutionPath != null).length;
+            const filteredParseWarnings = filtered.filter((i) => i.category === "parse").length;
+            result.issues = filtered;
+            result.summary = {
+                ...result.summary,
+                errors: filteredErrors,
+                warnings: filteredWarnings,
+                definiteErrors: filteredDefiniteErrors,
+                uncertainErrors: filteredUncertainErrors,
+                resolutionErrors: filteredResolutionErrors,
+                parseWarnings: filteredParseWarnings
+            };
+            result.unfilteredSummary = unfilteredSummary;
+            result.valid = filteredDefiniteErrors === 0;
+        }
+        // Apply warningCategoryFilter
+        if (input.warningCategoryFilter && input.warningCategoryFilter.length > 0) {
+            const allowedCategories = new Set(input.warningCategoryFilter);
+            result.issues = result.issues.filter((i) => i.category && allowedCategories.has(i.category));
+            if (result.structuredWarnings) {
+                result.structuredWarnings = result.structuredWarnings.filter((sw) => sw.category && allowedCategories.has(sw.category));
+                if (result.structuredWarnings.length === 0)
+                    result.structuredWarnings = undefined;
+            }
+            // Re-compute summary after category filter
+            const catErrors = result.issues.filter((i) => i.severity === "error").length;
+            const catWarnings = result.issues.filter((i) => i.severity === "warning").length;
+            const catDefiniteErrors = result.issues.filter((i) => i.severity === "error" && i.confidence !== "uncertain").length;
+            result.summary = {
+                ...result.summary,
+                errors: catErrors,
+                warnings: catWarnings,
+                definiteErrors: catDefiniteErrors,
+                uncertainErrors: result.issues.filter((i) => i.severity === "error" && i.confidence === "uncertain").length,
+                resolutionErrors: result.issues.filter((i) => i.resolutionPath != null).length,
+                parseWarnings: result.issues.filter((i) => i.category === "parse").length
+            };
+            result.valid = catDefiniteErrors === 0;
+        }
+        // Apply treatInfoAsWarning filter
+        if (input.treatInfoAsWarning === false && result.structuredWarnings) {
+            result.structuredWarnings = result.structuredWarnings.filter((sw) => sw.severity !== "info");
+            if (result.structuredWarnings.length === 0)
+                result.structuredWarnings = undefined;
+        }
+        // Apply compact report mode
+        if (input.reportMode === "compact") {
+            result.resolvedMembers = undefined;
+            result.structuredWarnings = undefined;
+            result.aggregatedWarnings = undefined;
+            result.toolHealth = undefined;
+            if (result.provenance) {
+                result.provenance.resolutionTrace = undefined;
+            }
+        }
+        return result;
+    }
+    async validateMixinBatch(input) {
+        const paths = input.sourcePaths;
+        const results = [];
+        let validCount = 0;
+        let invalidCount = 0;
+        let errorCount = 0;
+        // P5: default warningMode to "aggregated" in batch mode
+        const batchWarningMode = input.warningMode ?? "aggregated";
+        for (const sp of paths) {
+            try {
+                const singleResult = await this.validateMixin({
+                    ...input,
+                    sourcePaths: undefined,
+                    source: undefined,
+                    sourcePath: sp,
+                    warningMode: batchWarningMode
+                });
+                results.push({ sourcePath: sp, result: singleResult });
+                if (singleResult.valid) {
+                    validCount++;
+                }
+                else {
+                    invalidCount++;
+                }
+            }
+            catch (err) {
+                results.push({
+                    sourcePath: sp,
+                    error: err instanceof Error ? err.message : String(err)
+                });
+                errorCount++;
+            }
+        }
+        // Build issueSummary: aggregate issues across all results by (kind, confidence, category)
+        const issueGroupMap = new Map();
+        for (const r of results) {
+            if (!r.result)
+                continue;
+            for (const issue of r.result.issues) {
+                const key = `${issue.kind}\0${issue.confidence ?? "unknown"}\0${issue.category ?? "validation"}`;
+                const existing = issueGroupMap.get(key);
+                if (existing) {
+                    existing.count++;
+                    if (existing.sampleTargets.length < 3) {
+                        existing.sampleTargets.push(issue.target);
+                    }
+                }
+                else {
+                    issueGroupMap.set(key, {
+                        kind: issue.kind,
+                        confidence: issue.confidence ?? "unknown",
+                        category: issue.category ?? "validation",
+                        count: 1,
+                        sampleTargets: [issue.target]
+                    });
+                }
+            }
+        }
+        const issueSummary = issueGroupMap.size > 0
+            ? [...issueGroupMap.values()]
+            : undefined;
+        // Aggregate validation-level errors/warnings across all results
+        let totalValidationErrors = 0;
+        let totalValidationWarnings = 0;
+        for (const r of results) {
+            if (r.result) {
+                totalValidationErrors += r.result.summary.errors;
+                totalValidationWarnings += r.result.summary.warnings;
+            }
+        }
+        // Extract shared toolHealth from first result (all share same version/mapping)
+        const sharedHealth = results.find((r) => r.result?.toolHealth)?.result?.toolHealth;
+        // Batch confidenceScore = min of all individual scores
+        const scores = results
+            .map((r) => r.result?.confidenceScore)
+            .filter((s) => s != null);
+        const batchConfidenceScore = scores.length > 0 ? Math.min(...scores) : undefined;
+        return {
+            results,
+            summary: {
+                total: paths.length,
+                valid: validCount,
+                invalid: invalidCount,
+                errors: errorCount,
+                processingErrors: errorCount,
+                totalValidationErrors,
+                totalValidationWarnings,
+                confidenceScore: batchConfidenceScore
+            },
+            issueSummary,
+            toolHealth: sharedHealth
+        };
     }
     async validateAccessWidener(input) {
         const version = input.version.trim();
@@ -2301,9 +3307,39 @@ export class SourceService {
         // Contains matches need more candidates
         return base;
     }
+    extractClassMetadata(filePath, content) {
+        const lines = content.split(/\r?\n/);
+        const symbols = extractSymbolsFromSource(filePath, content);
+        const outputParts = [];
+        // Include package + import header (lines before first symbol declaration)
+        const firstSymbolLine = symbols.length > 0 ? symbols[0].line : lines.length + 1;
+        for (let i = 0; i < Math.min(firstSymbolLine - 1, lines.length); i++) {
+            const line = lines[i];
+            const trimmed = line.trim();
+            if (trimmed.startsWith("package ") || trimmed.startsWith("import ") || trimmed === "") {
+                outputParts.push(line);
+            }
+        }
+        // Add each symbol's declaration line
+        for (const symbol of symbols) {
+            const lineIndex = symbol.line - 1;
+            if (lineIndex >= 0 && lineIndex < lines.length) {
+                const prefix = symbol.symbolKind === "class" || symbol.symbolKind === "interface" ||
+                    symbol.symbolKind === "enum" || symbol.symbolKind === "record"
+                    ? `\n// [${symbol.symbolKind}] line ${symbol.line}`
+                    : `// [${symbol.symbolKind}] line ${symbol.line}`;
+                outputParts.push(prefix);
+                outputParts.push(lines[lineIndex]);
+            }
+        }
+        return outputParts.join("\n");
+    }
     resolveClassFilePath(artifactId, className) {
         const normalizedClassName = className.trim();
-        const classPath = normalizePathStyle(normalizedClassName.replace(/\./g, "/"));
+        const classPath = classNameToClassPath(normalizedClassName);
+        if (!classPath) {
+            return undefined;
+        }
         const candidates = new Set([`${classPath}.java`]);
         const innerIndex = classPath.indexOf("$");
         if (innerIndex > 0) {
@@ -2320,10 +3356,14 @@ export class SourceService {
             return undefined;
         }
         const classPathBySymbol = this.symbolsRepo.findBestClassFilePath(artifactId, normalizedClassName, simpleName);
-        if (classPathBySymbol) {
+        if (classPathBySymbol && isPackageCompatible(classPathBySymbol, classPath)) {
             return classPathBySymbol;
         }
-        return this.filesRepo.findFirstFilePathByName(artifactId, `${simpleName}.java`);
+        const byName = this.filesRepo.findFirstFilePathByName(artifactId, `${simpleName}.java`);
+        if (byName && isPackageCompatible(byName, classPath)) {
+            return byName;
+        }
+        return undefined;
     }
     findNearestSymbolForLine(artifactId, filePath, line, symbolKind) {
         const symbols = this.symbolsRepo
@@ -2569,8 +3609,9 @@ export class SourceService {
         };
     }
     async remapSignatureMembers(members, kind, version, mapping, sourcePriority, warnings) {
+        const failedNames = new Set();
         if (mapping === "official") {
-            return members;
+            return { members, failedNames };
         }
         // Build deduplicated lookup tables for member names and owner FQNs
         const memberKeyToRemapped = new Map();
@@ -2584,60 +3625,83 @@ export class SourceService {
                 ownerToRemapped.set(member.ownerFqn, member.ownerFqn); // default = official FQN
             }
         }
-        // Remap unique member names
-        const memberEntries = [...memberKeyToRemapped.entries()];
-        await Promise.all(memberEntries.map(async ([key, _officialName]) => {
-            const [ownerFqn, name, descriptor] = key.split("\0");
+        // Phase 1: Remap owner FQNs first (needed for member disambiguation)
+        const ownerEntries = [...ownerToRemapped.entries()];
+        await Promise.all(ownerEntries.map(async ([officialFqn]) => {
             try {
                 const mapped = await this.mappingService.findMapping({
                     version,
-                    kind,
-                    name,
-                    owner: ownerFqn,
-                    descriptor: kind === "method" ? descriptor : undefined,
+                    kind: "class",
+                    name: officialFqn,
                     sourceMapping: "official",
                     targetMapping: mapping,
                     sourcePriority
                 });
                 if (mapped.resolved && mapped.resolvedSymbol) {
-                    memberKeyToRemapped.set(key, mapped.resolvedSymbol.name);
-                }
-                else {
-                    warnings.push(`Could not remap ${kind} "${name}" to ${mapping}.`);
+                    ownerToRemapped.set(officialFqn, mapped.resolvedSymbol.name);
                 }
             }
             catch {
-                warnings.push(`Remap failed for ${kind} "${name}".`);
+                // keep official FQN as fallback
             }
         }));
-        // Remap unique owner FQNs
-        const ownerEntries = [...ownerToRemapped.entries()];
-        await Promise.all(ownerEntries.map(async ([officialFqn]) => {
+        // Phase 2: Remap member names using resolved owners for disambiguation
+        const memberEntries = [...memberKeyToRemapped.entries()];
+        await Promise.all(memberEntries.map(async ([key, _officialName]) => {
+            const [ownerFqn, name, descriptor] = key.split("\0");
             try {
+                const targetOwner = ownerToRemapped.get(ownerFqn) ?? ownerFqn;
                 const mapped = await this.mappingService.findMapping({
                     version,
-                    kind: "class",
-                    name: officialFqn,
+                    kind,
+                    name,
+                    owner: ownerFqn,
+                    descriptor: kind === "method" ? descriptor : undefined,
                     sourceMapping: "official",
                     targetMapping: mapping,
-                    sourcePriority
+                    sourcePriority,
+                    disambiguation: { ownerHint: targetOwner }
                 });
                 if (mapped.resolved && mapped.resolvedSymbol) {
-                    ownerToRemapped.set(officialFqn, mapped.resolvedSymbol.name);
+                    memberKeyToRemapped.set(key, mapped.resolvedSymbol.name);
+                }
+                else if (mapped.status === "ambiguous" && mapped.candidates && mapped.candidates.length > 0) {
+                    // Disambiguate: filter by target owner and pick the best candidate
+                    const ownerMatched = mapped.candidates.filter((c) => c.owner === targetOwner);
+                    const best = ownerMatched.length > 0 ? ownerMatched : mapped.candidates;
+                    if (best.length > 0) {
+                        memberKeyToRemapped.set(key, best[0].name);
+                        // Only mark as failed if the best candidate is not a high-confidence match
+                        if (best[0].confidence < 0.9) {
+                            failedNames.add(name);
+                        }
+                    }
+                    else {
+                        warnings.push(`Could not remap ${kind} "${name}" to ${mapping}.`);
+                        failedNames.add(name);
+                    }
+                }
+                else {
+                    warnings.push(`Could not remap ${kind} "${name}" to ${mapping}.`);
+                    failedNames.add(name);
                 }
             }
             catch {
-                // keep official FQN as fallback
+                warnings.push(`Remap failed for ${kind} "${name}".`);
+                failedNames.add(name);
             }
         }));
-        return members.map((member) => {
-            const memberKey = `${member.ownerFqn}\0${member.name}\0${member.jvmDescriptor}`;
-            return {
-                ...member,
-                name: memberKeyToRemapped.get(memberKey) ?? member.name,
-                ownerFqn: ownerToRemapped.get(member.ownerFqn) ?? member.ownerFqn
-            };
-        });
+        return {
+            members: members.map((member) => {
+                const memberKey = `${member.ownerFqn}\0${member.name}\0${member.jvmDescriptor}`;
+                return {
+                    ...member,
+                    name: memberKeyToRemapped.get(memberKey) ?? member.name,
+                    ownerFqn: ownerToRemapped.get(member.ownerFqn) ?? member.ownerFqn
+                };
+            }),
+            failedNames
+        };
     }
     fallbackArtifactSignature(artifactId) {
         return createHash("sha256").update(artifactId).digest("hex");
@@ -2748,6 +3812,25 @@ export class SourceService {
                     contentHash: createHash("sha256").update(entry.content).digest("hex")
                 }));
             }
+            catch (caughtError) {
+                if (isAppError(caughtError) && caughtError.code === ERROR_CODES.DECOMPILER_FAILED) {
+                    throw createError({
+                        code: ERROR_CODES.DECOMPILER_FAILED,
+                        message: caughtError.message,
+                        details: {
+                            ...(caughtError.details ?? {}),
+                            artifactId: resolved.artifactId,
+                            binaryJarPath: resolved.binaryJarPath,
+                            producedJavaCount: typeof caughtError.details?.producedJavaCount === "number"
+                                ? caughtError.details.producedJavaCount
+                                : 0,
+                            nextAction: "Verify Java runtime and Vineflower availability, then retry. If available, prefer source-backed artifacts.",
+                            recommendedCommand: "echo $MCP_VINEFLOWER_JAR_PATH"
+                        }
+                    });
+                }
+                throw caughtError;
+            }
             finally {
                 this.metrics.recordDuration("decompile_duration_ms", Date.now() - decompileStartedAt);
             }
@@ -2756,7 +3839,11 @@ export class SourceService {
             throw createError({
                 code: ERROR_CODES.SOURCE_NOT_FOUND,
                 message: "No source artifact available.",
-                details: { artifactId: resolved.artifactId }
+                details: {
+                    artifactId: resolved.artifactId,
+                    nextAction: "Use list-artifact-files to inspect the artifact's contents.",
+                    suggestedCall: { tool: "list-artifact-files", params: { artifactId: resolved.artifactId } }
+                }
             });
         }
         const symbols = [];
@@ -2790,7 +3877,11 @@ export class SourceService {
             throw createError({
                 code: ERROR_CODES.SOURCE_NOT_FOUND,
                 message: "Artifact not found. Resolve context first.",
-                details: { artifactId }
+                details: {
+                    artifactId,
+                    nextAction: "Use resolve-artifact to resolve a source artifact first.",
+                    suggestedCall: { tool: "resolve-artifact", params: { targetKind: "version", targetValue: "latest" } }
+                }
             });
         }
         return artifact;