@adhisang/minecraft-modding-mcp 1.2.1 → 2.0.0

package/dist/source-service.js

@@ -80,6 +80,23 @@ function hasExactVersionToken(path, version) {
     const pattern = new RegExp(`(^|[^0-9a-z])${escapeRegexLiteral(normalizedVersion)}([^0-9a-z]|$)`, "i");
     return pattern.test(normalizedPath);
 }
+function looksLikeDeobfuscatedClassName(value) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return false;
+    }
+    if (trimmed.startsWith("net.minecraft.") || trimmed.startsWith("com.mojang.")) {
+        return true;
+    }
+    const simpleName = trimmed.split(/[.$]/).at(-1) ?? trimmed;
+    return /^[A-Z][A-Za-z0-9_$]{2,}$/.test(simpleName);
+}
+function obfuscatedNamespaceHint(className) {
+    return `Artifact is indexed in obfuscated runtime names. Deobfuscated names like "${className}" usually require mapping="mojang" or a find-mapping lookup to obfuscated names.`;
+}
+function hasPartialNetMinecraftCoverage(qualityFlags) {
+    return qualityFlags.includes("partial-source-no-net-minecraft");
+}
 function normalizeOptionalProjectPath(projectPath) {
     if (!projectPath) {
         return undefined;
@@ -168,9 +185,9 @@ const COMMON_SOURCE_ROOTS = [
 ];
 function normalizeMapping(mapping) {
     if (mapping == null) {
-        return "official";
+        return "obfuscated";
     }
-    if (mapping === "official" ||
+    if (mapping === "obfuscated" ||
         mapping === "mojang" ||
         mapping === "intermediary" ||
         mapping === "yarn") {
@@ -181,8 +198,8 @@ function normalizeMapping(mapping) {
         message: `Unsupported mapping "${mapping}".`,
         details: {
             mapping,
-            nextAction: "Try mapping=official which is always available.",
-            suggestedCall: { tool: "resolve-artifact", params: { mapping: "official" } }
+            nextAction: "Try mapping=obfuscated which is always available.",
+            suggestedCall: { tool: "resolve-artifact", params: { mapping: "obfuscated" } }
         }
     });
 }
@@ -194,7 +211,7 @@ function normalizeAccessWidenerNamespace(namespace) {
     if (normalized === "named") {
         return "yarn";
     }
-    if (normalized === "official" ||
+    if (normalized === "obfuscated" ||
         normalized === "mojang" ||
         normalized === "intermediary" ||
         normalized === "yarn") {
@@ -333,7 +350,7 @@ function canUseIndexedSearchPath(indexedSearchEnabled, intent, match, _scope) {
     if (match === "regex") {
         return false;
     }
-    // fileGlob and symbolKind are now applied as post-filters on indexed candidates
+    // packagePrefix and fileGlob are applied as post-filters on indexed candidates.
     return true;
 }
 function buildGlobRegex(pattern) {
@@ -412,14 +429,6 @@ function checkPackagePrefix(filePath, packagePrefix) {
     const normalizedPrefix = packagePrefix.replace(/\.+/g, "/").replace(/\/+$/, "");
     return normalizePathStyle(filePath).startsWith(`${normalizedPrefix}/`);
 }
-function buildSnippetWindow(lines) {
-    const totalLines = clampLimit(lines, 8, 80);
-    const before = Math.floor((totalLines - 1) / 2);
-    return {
-        before,
-        after: Math.max(0, totalLines - 1 - before)
-    };
-}
 function buildSearchCursorContext(input) {
     return JSON.stringify({
         artifactId: input.artifactId,
@@ -427,7 +436,6 @@ function buildSearchCursorContext(input) {
         intent: input.intent,
         match: input.match,
         queryMode: input.queryMode,
-        includeDefinition: input.includeDefinition,
         packagePrefix: input.scope?.packagePrefix ?? "",
         fileGlob: input.scope?.fileGlob ?? "",
         symbolKind: input.scope?.symbolKind ?? ""
@@ -521,41 +529,6 @@ function matchRegexIndex(target, regex) {
     const result = regex.exec(target);
     return result?.index ?? -1;
 }
-function indexToLine(content, index) {
-    if (index <= 0) {
-        return 1;
-    }
-    return content.slice(0, index).split(/\r?\n/).length;
-}
-function lineToSymbol(symbol) {
-    if (!isSymbolKind(symbol.symbolKind)) {
-        return undefined;
-    }
-    return {
-        symbolKind: symbol.symbolKind,
-        symbolName: symbol.symbolName,
-        qualifiedName: symbol.qualifiedName,
-        line: symbol.line
-    };
-}
-function toContextSnippet(content, centerLineInput, beforeLines, afterLines, withLineNumbers) {
-    const lines = content.split(/\r?\n/);
-    const centerLine = Math.min(Math.max(1, centerLineInput), Math.max(lines.length, 1));
-    const requestedStart = Math.max(1, centerLine - beforeLines);
-    const requestedEnd = centerLine + afterLines;
-    const startLine = Math.min(requestedStart, Math.max(lines.length, 1));
-    const endLine = Math.min(requestedEnd, Math.max(lines.length, 1));
-    const snippetLines = lines.slice(startLine - 1, endLine);
-    const snippet = withLineNumbers
-        ? snippetLines.map((line, index) => `${startLine + index}: ${line}`).join("\n")
-        : snippetLines.join("\n");
-    return {
-        startLine,
-        endLine,
-        snippet,
-        truncated: requestedStart !== startLine || requestedEnd !== endLine
-    };
-}
 function chunkArray(items, chunkSize) {
     const size = Math.max(1, Math.trunc(chunkSize));
     if (items.length === 0) {
@@ -663,11 +636,12 @@ export class SourceService {
         const selected = candidates.find((candidate) => candidate.hasMinecraftNamespace) ?? candidates[0];
         const candidateArtifacts = candidates
             .slice(0, 20)
-            .map((candidate) => `${candidate.jarPath}#java=${candidate.javaEntryCount}`);
+            .map((candidate) => `${candidate.jarPath}#java=${candidate.javaEntryCount}#net_minecraft=${candidate.hasMinecraftNamespace ? 1 : 0}`);
         return {
             searchedPaths,
             candidateArtifacts,
-            selectedSourceJarPath: selected?.jarPath
+            selectedSourceJarPath: selected?.jarPath,
+            selectedHasMinecraftNamespace: selected?.hasMinecraftNamespace
         };
     }
     buildVersionSourceRecoveryCommand(projectPath) {
@@ -734,13 +708,13 @@ export class SourceService {
                     // coordinate validity is validated by resolver, keep version undefined on parse failure.
                 }
             }
-            // Unobfuscated versions (MC 26.1+) ship with official names; intermediary/yarn are not applicable.
+            // Unobfuscated versions (MC 26.1+) ship with deobfuscated runtime names; intermediary/yarn are not applicable.
             let effectiveMapping = mapping;
             if ((mapping === "intermediary" || mapping === "yarn") &&
                 resolvedVersion &&
                 isUnobfuscatedVersion(resolvedVersion)) {
-                warnings.push(`Version ${resolvedVersion} is unobfuscated; ${mapping} mappings are not applicable. Using official names.`);
-                effectiveMapping = "official";
+                warnings.push(`Version ${resolvedVersion} is unobfuscated; ${mapping} mappings are not applicable. Using the obfuscated namespace label for the deobfuscated runtime names.`);
+                effectiveMapping = "obfuscated";
             }
             if (kind === "version" && resolvedVersion && effectiveMapping === "mojang" && scope !== "vanilla") {
                 versionSourceDiscovery = await this.discoverVersionSourceJar({
@@ -797,18 +771,18 @@ export class SourceService {
                     else if (isVanillaMojang) {
                         suggestedCall = {
                             tool: "resolve-artifact",
-                            params: { targetKind: kind, targetValue: value, mapping: "official", scope: "vanilla" }
+                            params: { targetKind: kind, targetValue: value, mapping: "obfuscated", scope: "vanilla" }
                         };
                         nextAction =
                             "scope=vanilla blocks Loom cache discovery needed for mojang mapping. " +
-                                "Without a projectPath, use mapping=official to read vanilla obfuscated names.";
+                                "Without a projectPath, use mapping=obfuscated to read vanilla runtime names directly.";
                     }
                     else {
                         suggestedCall = {
                             tool: "resolve-artifact",
-                            params: { targetKind: kind, targetValue: value, mapping: "official", ...(scope ? { scope } : {}) }
+                            params: { targetKind: kind, targetValue: value, mapping: "obfuscated", ...(scope ? { scope } : {}) }
                         };
-                        nextAction = "Retry with mapping=official to use obfuscated names.";
+                        nextAction = "Retry with mapping=obfuscated to use the runtime obfuscated namespace.";
                     }
                     throw createError({
                         code: ERROR_CODES.MAPPING_NOT_APPLIED,
@@ -841,7 +815,7 @@ export class SourceService {
                 }
                 const mappingAvailability = await this.mappingService.ensureMappingAvailable({
                     version: resolved.version,
-                    sourceMapping: "official",
+                    sourceMapping: "obfuscated",
                     targetMapping: effectiveMapping,
                     sourcePriority: input.sourcePriority
                 });
@@ -864,6 +838,10 @@ export class SourceService {
             }
             if (versionSourceDiscovery?.selectedSourceJarPath) {
                 resolved.qualityFlags.push("source-jar-validated");
+                if (versionSourceDiscovery.selectedHasMinecraftNamespace === false) {
+                    resolved.qualityFlags.push("partial-source-no-net-minecraft");
+                    warnings.push(`Source coverage does not include net.minecraft for ${versionSourceDiscovery.selectedSourceJarPath}; class lookups may fall back to the binary artifact.`);
+                }
                 if (kind === "version" && !hasExactVersionToken(versionSourceDiscovery.selectedSourceJarPath, value)) {
                     if (input.strictVersion) {
                         throw createError({
@@ -942,8 +920,7 @@ export class SourceService {
             if (!query) {
                 return {
                     hits: [],
-                    totalApprox: 0,
-                    mappingApplied: artifact.mappingApplied ?? "official"
+                    mappingApplied: artifact.mappingApplied ?? "obfuscated"
                 };
             }
             const intent = normalizeIntent(input.intent);
@@ -961,12 +938,15 @@ export class SourceService {
             const searchLimitCap = match === "regex"
                 ? Math.max(1, Math.min(this.config.maxSearchHits, MAX_REGEX_RESULT_LIMIT))
                 : this.config.maxSearchHits;
+            const scope = input.scope;
+            if (scope?.symbolKind && intent !== "symbol") {
+                throw createError({
+                    code: ERROR_CODES.INVALID_INPUT,
+                    message: 'symbolKind filter is only supported when intent="symbol".'
+                });
+            }
             const limit = clampLimit(input.limit, 20, searchLimitCap);
-            const includeDefinition = input.include?.includeDefinition ?? false;
-            const includeOneHop = input.include?.includeOneHop ?? false;
-            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,
@@ -974,8 +954,7 @@ export class SourceService {
                 intent,
                 match,
                 queryMode,
-                scope,
-                includeDefinition
+                scope
             });
             const decodedCursor = decodeSearchCursor(input.cursor);
             const cursor = decodedCursor?.contextKey === cursorContext ? decodedCursor : undefined;
@@ -991,52 +970,35 @@ export class SourceService {
             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
-                if (match !== "regex") {
-                    const approxCount = this.symbolsRepo.countScopedSymbols({
-                        artifactId: artifact.artifactId,
-                        query,
-                        match,
-                        symbolKind: scope?.symbolKind,
-                        packagePrefix: scope?.packagePrefix
-                    });
-                    accumulator.setTotalApproxOverride(approxCount);
-                }
+                this.searchSymbolIntent(artifact.artifactId, query, match, scope, regexPattern, recordHit);
             }
             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);
+                this.searchTextIntent(artifact.artifactId, query, match, scope, regexPattern, recordHit);
             }
             else if (!indexedSearchEnabled) {
                 this.metrics.recordIndexedDisabled();
                 if (!tokenOnlyTextIntent) {
                     this.metrics.recordSearchFallback();
                     if (intent === "path") {
-                        this.searchPathIntent(artifact.artifactId, query, match, scope, includeDefinition, snippetWindow, regexPattern, recordHit);
+                        this.searchPathIntent(artifact.artifactId, query, match, scope, regexPattern, recordHit);
                     }
                     else {
-                        this.searchTextIntent(artifact.artifactId, query, match, scope, includeDefinition, snippetWindow, regexPattern, recordHit);
+                        this.searchTextIntent(artifact.artifactId, query, match, scope, regexPattern, recordHit);
                     }
                 }
             }
             else if (canUseIndexedSearchPath(indexedSearchEnabled, intent, match, scope)) {
                 try {
                     if (intent === "path") {
-                        this.searchPathIntentIndexed(artifact.artifactId, query, match, scope, includeDefinition, snippetWindow, recordHit);
-                        // WS4: Use repo-level COUNT for totalApprox instead of accumulator count
-                        const approxCount = this.filesRepo.countPathCandidates(artifact.artifactId, query);
-                        accumulator.setTotalApproxOverride(approxCount);
+                        this.searchPathIntentIndexed(artifact.artifactId, query, match, scope, recordHit);
                     }
                     else {
-                        this.searchTextIntentIndexed(artifact.artifactId, query, match, scope, includeDefinition, snippetWindow, recordHit);
-                        // WS4: Use repo-level COUNT for totalApprox instead of accumulator count
-                        const approxCount = this.filesRepo.countTextCandidates(artifact.artifactId, query);
-                        accumulator.setTotalApproxOverride(approxCount);
+                        this.searchTextIntentIndexed(artifact.artifactId, query, match, scope, recordHit);
                         // 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.searchTextIntent(artifact.artifactId, query, match, scope, regexPattern, recordHit);
                         }
                     }
                     this.metrics.recordSearchIndexedHit();
@@ -1052,10 +1014,10 @@ export class SourceService {
                     // 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);
+                            this.searchPathIntent(artifact.artifactId, query, match, scope, regexPattern, recordHit);
                         }
                         else {
-                            this.searchTextIntent(artifact.artifactId, query, match, scope, includeDefinition, snippetWindow, regexPattern, recordHit);
+                            this.searchTextIntent(artifact.artifactId, query, match, scope, regexPattern, recordHit);
                         }
                     }
                 }
@@ -1064,10 +1026,10 @@ export class SourceService {
                 if (!tokenOnlyTextIntent) {
                     this.metrics.recordSearchFallback();
                     if (intent === "path") {
-                        this.searchPathIntent(artifact.artifactId, query, match, scope, includeDefinition, snippetWindow, regexPattern, recordHit);
+                        this.searchPathIntent(artifact.artifactId, query, match, scope, regexPattern, recordHit);
                     }
                     else {
-                        this.searchTextIntent(artifact.artifactId, query, match, scope, includeDefinition, snippetWindow, regexPattern, recordHit);
+                        this.searchTextIntent(artifact.artifactId, query, match, scope, regexPattern, recordHit);
                     }
                 }
             }
@@ -1078,31 +1040,11 @@ export class SourceService {
             const nextCursor = finalizedHits.nextCursorHit
                 ? encodeSearchCursor(finalizedHits.nextCursorHit, cursorContext)
                 : undefined;
-            const relations = includeOneHop
-                ? this.buildOneHopRelations(artifact.artifactId, page.flatMap((hit) => hit.symbol && isSymbolKind(hit.symbol.symbolKind)
-                    ? [
-                        {
-                            symbolKind: hit.symbol.symbolKind,
-                            symbolName: hit.symbol.symbolName,
-                            filePath: hit.filePath,
-                            line: hit.symbol.line
-                        }
-                    ]
-                    : []), 10)
-                : undefined;
-            if (relations?.length) {
-                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;
+            this.metrics.recordSearchTokenBytesReturned(Buffer.byteLength(JSON.stringify({ hits: page }), "utf8"));
             return {
                 hits: page,
-                relations: relations && relations.length > 0 ? relations : undefined,
                 nextCursor,
-                totalApprox,
-                mappingApplied: artifact.mappingApplied ?? "official"
+                mappingApplied: artifact.mappingApplied ?? "obfuscated"
             };
         }
         finally {
@@ -1139,7 +1081,7 @@ export class SourceService {
                 content,
                 contentBytes: fullBytes,
                 truncated,
-                mappingApplied: artifact.mappingApplied ?? "official"
+                mappingApplied: artifact.mappingApplied ?? "obfuscated"
             };
         }
         finally {
@@ -1159,7 +1101,7 @@ export class SourceService {
             return {
                 items: page.items,
                 nextCursor: page.nextCursor,
-                mappingApplied: artifact.mappingApplied ?? "official"
+                mappingApplied: artifact.mappingApplied ?? "obfuscated"
             };
         }
         finally {
@@ -1304,12 +1246,13 @@ export class SourceService {
         }
         const mappingApplied = workspaceDetection.mappingApplied;
         if (kind === "method") {
+            const methodOwner = owner;
+            const methodDescriptor = descriptor;
             const exact = await this.mappingService.resolveMethodMappingExact({
                 version,
-                kind: "method",
-                owner,
+                owner: methodOwner,
                 name,
-                descriptor: descriptor,
+                descriptor: methodDescriptor,
                 sourceMapping: input.sourceMapping,
                 targetMapping: mappingApplied,
                 sourcePriority: input.sourcePriority
@@ -1473,14 +1416,14 @@ export class SourceService {
             try {
                 let resolvedSymbols = resolvedSymbolsByVersion.get(version);
                 if (!resolvedSymbols) {
-                    const [officialClassName, officialMethod] = await Promise.all([
-                        this.resolveToOfficialClassName(userClassName, version, mapping, input.sourcePriority, warnings),
-                        this.resolveToOfficialMemberName(userMethodName, userClassName, descriptor, "method", version, mapping, input.sourcePriority, warnings)
+                    const [obfuscatedClassName, obfuscatedMethod] = await Promise.all([
+                        this.resolveToObfuscatedClassName(userClassName, version, mapping, input.sourcePriority, warnings),
+                        this.resolveToObfuscatedMemberName(userMethodName, userClassName, descriptor, "method", version, mapping, input.sourcePriority, warnings)
                     ]);
                     resolvedSymbols = {
-                        className: officialClassName,
-                        methodName: officialMethod.name,
-                        methodDescriptor: officialMethod.descriptor
+                        className: obfuscatedClassName,
+                        methodName: obfuscatedMethod.name,
+                        methodDescriptor: obfuscatedMethod.descriptor
                     };
                     resolvedSymbolsByVersion.set(version, resolvedSymbols);
                 }
@@ -1630,18 +1573,18 @@ export class SourceService {
             });
         }
         const mappingWarnings = [];
-        const officialFromClassName = await this.resolveToOfficialClassName(className, fromVersion, mapping, input.sourcePriority, mappingWarnings);
-        const officialToClassName = fromVersion === toVersion
-            ? officialFromClassName
-            : await this.resolveToOfficialClassName(className, toVersion, mapping, input.sourcePriority, mappingWarnings);
+        const obfuscatedFromClassName = await this.resolveToObfuscatedClassName(className, fromVersion, mapping, input.sourcePriority, mappingWarnings);
+        const obfuscatedToClassName = fromVersion === toVersion
+            ? obfuscatedFromClassName
+            : await this.resolveToObfuscatedClassName(className, toVersion, mapping, input.sourcePriority, mappingWarnings);
         const [fromResolved, toResolved] = await Promise.all([
             this.versionService.resolveVersionJar(fromVersion),
             this.versionService.resolveVersionJar(toVersion)
         ]);
-        const loadSignature = async (version, jarPath, officialClassName) => {
+        const loadSignature = async (version, jarPath, obfuscatedClassName) => {
             try {
                 const signature = await this.explorerService.getSignature({
-                    fqn: officialClassName,
+                    fqn: obfuscatedClassName,
                     jarPath,
                     access: "all",
                     includeSynthetic: false,
@@ -1662,8 +1605,8 @@ export class SourceService {
             }
         };
         const [fromSignature, toSignature] = await Promise.all([
-            loadSignature(fromVersion, fromResolved.jarPath, officialFromClassName),
-            loadSignature(toVersion, toResolved.jarPath, officialToClassName)
+            loadSignature(fromVersion, fromResolved.jarPath, obfuscatedFromClassName),
+            loadSignature(toVersion, toResolved.jarPath, obfuscatedToClassName)
         ]);
         const warnings = [...mappingWarnings];
         if (fromSignature) {
@@ -1740,16 +1683,16 @@ export class SourceService {
                 : classChange === "absent_in_both"
                     ? emptyDiffDelta()
                     : diffMembersByKey(fromMembers.fields, toMembers.fields, (member) => member.name, true);
-        // Remap diff delta members for non-official mappings
+        // Remap diff delta members for non-obfuscated mappings
         const remapDelta = async (delta, kind) => {
             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)
+                this.remapSignatureMembers(delta.added, kind, toVersion, "obfuscated", mapping, input.sourcePriority, warnings),
+                this.remapSignatureMembers(delta.removed, kind, fromVersion, "obfuscated", mapping, input.sourcePriority, warnings)
             ]);
             const remappedModified = await Promise.all(delta.modified.map(async (change) => {
                 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)
+                    this.remapSignatureMembers([change.from], kind, fromVersion, "obfuscated", mapping, input.sourcePriority, warnings),
+                    this.remapSignatureMembers([change.to], kind, toVersion, "obfuscated", mapping, input.sourcePriority, warnings)
                 ]);
                 return { ...change, from: fromResult.members[0], to: toResult.members[0] };
             }));
@@ -1817,7 +1760,7 @@ export class SourceService {
             });
         }
         // Verify artifact exists
-        this.getArtifact(artifactId);
+        const artifact = this.getArtifact(artifactId);
         const limit = Math.max(1, Math.min(input.limit ?? 20, 200));
         const warnings = [];
         const isQualified = className.includes(".");
@@ -1847,7 +1790,17 @@ export class SourceService {
                 symbolKind: row.symbolKind
             }))
                 .slice(0, limit);
-            return { matches, total: matches.length, warnings };
+            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) {
+                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 && artifact.mappingApplied === "obfuscated" && looksLikeDeobfuscatedClassName(className)) {
+                warnings.push(`No exact class symbol matched "${className}". ${obfuscatedNamespaceHint(className)}`);
+            }
+            return { matches: filteredMatches, total: filteredMatches.length, warnings };
         }
         // Simple name: search for exact symbol name match among type symbols
         const result = this.symbolsRepo.findScopedSymbols({
@@ -1871,7 +1824,17 @@ export class SourceService {
                 symbolKind: row.symbolKind
             });
         }
-        return { matches, total: matches.length, warnings };
+        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) {
+            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 && artifact.mappingApplied === "obfuscated" && looksLikeDeobfuscatedClassName(className)) {
+            warnings.push(`No exact class symbol matched "${className}". ${obfuscatedNamespaceHint(className)}`);
+        }
+        return { matches: filteredMatches, total: filteredMatches.length, warnings };
     }
     async getClassSource(input) {
         const className = input.className.trim();
@@ -1919,6 +1882,10 @@ export class SourceService {
         let mappingApplied = requestedMapping;
         let provenance;
         let qualityFlags = [];
+        let sourceJarPath;
+        let binaryJarPath;
+        let version;
+        let coordinate;
         if (!artifactId) {
             if (!input.target) {
                 throw createError({
@@ -1943,6 +1910,10 @@ export class SourceService {
             mappingApplied = resolved.mappingApplied;
             provenance = resolved.provenance;
             qualityFlags = [...resolved.qualityFlags];
+            sourceJarPath = resolved.resolvedSourceJarPath;
+            binaryJarPath = resolved.binaryJarPath;
+            version = resolved.version;
+            coordinate = resolved.coordinate;
         }
         else {
             const artifact = this.getArtifact(artifactId);
@@ -1951,53 +1922,122 @@ export class SourceService {
             mappingApplied = artifact.mappingApplied ?? requestedMapping;
             provenance = artifact.provenance;
             qualityFlags = artifact.qualityFlags;
+            sourceJarPath = artifact.sourceJarPath;
+            binaryJarPath = artifact.binaryJarPath;
+            version = artifact.version;
+            coordinate = artifact.coordinate;
+        }
+        let activeArtifactId = artifactId;
+        let activeOrigin = origin;
+        let activeProvenance = provenance;
+        let activeQualityFlags = [...qualityFlags];
+        let activeMappingApplied = mappingApplied;
+        let activeSourceJarPath = sourceJarPath;
+        let attemptedBinaryFallback = false;
+        const tryBinaryFallback = async () => {
+            if (attemptedBinaryFallback) {
+                return false;
+            }
+            attemptedBinaryFallback = true;
+            const normalizedBinaryJarPath = normalizeOptionalString(binaryJarPath);
+            if (!normalizedBinaryJarPath) {
+                return false;
+            }
+            if (activeSourceJarPath &&
+                normalizePathStyle(activeSourceJarPath) === normalizePathStyle(normalizedBinaryJarPath)) {
+                return false;
+            }
+            const fallbackResolved = await this.resolveBinaryFallbackArtifact({
+                binaryJarPath: normalizedBinaryJarPath,
+                version,
+                coordinate,
+                requestedMapping,
+                mappingApplied,
+                provenance: activeProvenance,
+                qualityFlags: activeQualityFlags
+            });
+            if (!fallbackResolved || fallbackResolved.artifactId === activeArtifactId) {
+                return false;
+            }
+            activeArtifactId = fallbackResolved.artifactId;
+            activeOrigin = fallbackResolved.origin;
+            activeMappingApplied = fallbackResolved.mappingApplied ?? activeMappingApplied;
+            activeProvenance = fallbackResolved.provenance ?? activeProvenance;
+            activeQualityFlags = [...new Set([...(fallbackResolved.qualityFlags ?? []), "binary-fallback"])];
+            activeSourceJarPath = fallbackResolved.sourceJarPath;
+            warnings.push(`Falling back to binary artifact "${normalizedBinaryJarPath}" because source coverage for "${className}" was incomplete.`);
+            if (activeMappingApplied !== requestedMapping) {
+                warnings.push(`Fallback source text is indexed in ${activeMappingApplied} names; returned source is not remapped to ${requestedMapping}.`);
+            }
+            return true;
+        };
+        let activeLookupClassName = await this.resolveClassNameForLookup({
+            className,
+            version,
+            sourceMapping: requestedMapping,
+            targetMapping: activeMappingApplied,
+            sourcePriority: input.sourcePriority,
+            warnings,
+            context: "source lookup"
+        });
+        let filePath = this.resolveClassFilePath(activeArtifactId, activeLookupClassName);
+        if (!filePath && (await tryBinaryFallback())) {
+            activeLookupClassName = await this.resolveClassNameForLookup({
+                className,
+                version,
+                sourceMapping: requestedMapping,
+                targetMapping: activeMappingApplied,
+                sourcePriority: input.sourcePriority,
+                warnings,
+                context: "source lookup"
+            });
+            filePath = this.resolveClassFilePath(activeArtifactId, activeLookupClassName);
         }
-        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,
-                    ...(scope ? { scope } : {}),
-                    ...(targetKind ? { targetKind } : {}),
-                    ...(targetValue ? { targetValue } : {}),
-                    mapping: mappingApplied,
-                    nextAction,
-                    suggestedCall: { tool: "find-class", params: { className: simpleName, artifactId } }
-                }
+            throw this.buildClassSourceNotFoundError({
+                artifactId: activeArtifactId,
+                className,
+                lookupClassName: activeLookupClassName,
+                mappingApplied: activeMappingApplied,
+                requestedMapping,
+                qualityFlags: activeQualityFlags,
+                attemptedBinaryFallback,
+                targetKind: input.target?.kind,
+                targetValue: input.target?.value,
+                scope: input.scope,
+                projectPath: input.projectPath,
+                version
             });
         }
-        const row = this.filesRepo.getFileContent(artifactId, filePath);
+        let row = this.filesRepo.getFileContent(activeArtifactId, filePath);
+        if (!row && (await tryBinaryFallback())) {
+            activeLookupClassName = await this.resolveClassNameForLookup({
+                className,
+                version,
+                sourceMapping: requestedMapping,
+                targetMapping: activeMappingApplied,
+                sourcePriority: input.sourcePriority,
+                warnings,
+                context: "source lookup"
+            });
+            filePath = this.resolveClassFilePath(activeArtifactId, activeLookupClassName) ?? filePath;
+            row = this.filesRepo.getFileContent(activeArtifactId, 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,
-                    ...(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 } }
-                }
+            throw this.buildClassSourceNotFoundError({
+                artifactId: activeArtifactId,
+                className,
+                lookupClassName: activeLookupClassName,
+                mappingApplied: activeMappingApplied,
+                requestedMapping,
+                qualityFlags: activeQualityFlags,
+                attemptedBinaryFallback,
+                filePath,
+                targetKind: input.target?.kind,
+                targetValue: input.target?.value,
+                scope: input.scope,
+                projectPath: input.projectPath,
+                version
             });
         }
         const lines = row.content.split(/\r?\n/);
@@ -2048,12 +2088,12 @@ export class SourceService {
             resolvedOutputFile = outputPath;
             sourceText = `[Written to ${outputPath}]`;
         }
-        const normalizedProvenance = provenance ??
+        const normalizedProvenance = activeProvenance ??
             this.buildFallbackProvenance({
-                artifactId,
-                origin,
+                artifactId: activeArtifactId,
+                origin: activeOrigin,
                 requestedMapping,
-                mappingApplied
+                mappingApplied: activeMappingApplied
             });
         return {
             className,
@@ -2066,12 +2106,12 @@ export class SourceService {
             },
             truncated,
             ...(charsTruncated ? { charsTruncated } : {}),
-            origin,
-            artifactId,
+            origin: activeOrigin,
+            artifactId: activeArtifactId,
             requestedMapping,
-            mappingApplied,
+            mappingApplied: activeMappingApplied,
             provenance: normalizedProvenance,
-            qualityFlags,
+            qualityFlags: activeQualityFlags,
             ...(resolvedOutputFile ? { outputFile: resolvedOutputFile } : {}),
             warnings
         };
@@ -2148,10 +2188,10 @@ export class SourceService {
             binaryJarPath = artifact.binaryJarPath;
             version = artifact.version;
         }
-        if (requestedMapping !== "official" && !version) {
+        if (requestedMapping !== "obfuscated" && !version) {
             throw createError({
                 code: ERROR_CODES.MAPPING_NOT_APPLIED,
-                message: `Non-official mapping "${requestedMapping}" requires a version, but none was resolved.`,
+                message: `Non-obfuscated mapping "${requestedMapping}" requires a version, but none was resolved.`,
                 details: {
                     mapping: requestedMapping,
                     nextAction: "Resolve with targetKind=version or specify a versioned coordinate.",
@@ -2170,29 +2210,35 @@ export class SourceService {
                 }
             });
         }
-        const officialClassName = version != null
-            ? await this.resolveToOfficialClassName(className, version, requestedMapping, input.sourcePriority, warnings)
-            : className;
+        const lookupClassName = await this.resolveClassNameForLookup({
+            className,
+            version,
+            sourceMapping: requestedMapping,
+            targetMapping: mappingApplied,
+            sourcePriority: input.sourcePriority,
+            warnings,
+            context: "binary lookup"
+        });
         const signature = await this.explorerService.getSignature({
-            fqn: officialClassName,
+            fqn: lookupClassName,
             jarPath: binaryJarPath,
             access,
             includeSynthetic,
             includeInherited,
-            memberPattern: requestedMapping === "official" ? memberPattern : undefined
+            memberPattern: requestedMapping === mappingApplied ? memberPattern : undefined
         });
         warnings.push(...signature.warnings);
         let remappedConstructors = version != null
-            ? (await this.remapSignatureMembers(signature.constructors, "method", version, requestedMapping, input.sourcePriority, warnings)).members
+            ? (await this.remapSignatureMembers(signature.constructors, "method", version, mappingApplied, requestedMapping, input.sourcePriority, warnings)).members
             : signature.constructors;
         let remappedFields = version != null
-            ? (await this.remapSignatureMembers(signature.fields, "field", version, requestedMapping, input.sourcePriority, warnings)).members
+            ? (await this.remapSignatureMembers(signature.fields, "field", version, mappingApplied, requestedMapping, input.sourcePriority, warnings)).members
             : signature.fields;
         let remappedMethods = version != null
-            ? (await this.remapSignatureMembers(signature.methods, "method", version, requestedMapping, input.sourcePriority, warnings)).members
+            ? (await this.remapSignatureMembers(signature.methods, "method", version, mappingApplied, requestedMapping, input.sourcePriority, warnings)).members
             : signature.methods;
-        // Apply memberPattern post-remap for non-official mappings
-        if (requestedMapping !== "official" && memberPattern) {
+        // Apply memberPattern after remap when the lookup namespace differs from the requested namespace.
+        if (requestedMapping !== mappingApplied && memberPattern) {
             const lowerPattern = memberPattern.toLowerCase();
             remappedConstructors = remappedConstructors.filter((m) => m.name.toLowerCase().includes(lowerPattern));
             remappedFields = remappedFields.filter((m) => m.name.toLowerCase().includes(lowerPattern));
@@ -2248,91 +2294,68 @@ export class SourceService {
         };
     }
     async validateMixin(input) {
-        // 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"];
-                    }
+        const { input: sourceInput, ...sharedInput } = input;
+        const mode = sourceInput.mode;
+        if (mode === "inline") {
+            const singleResult = await this.validateMixinSingle({
+                ...sharedInput,
+                source: sourceInput.source
+            });
+            return this.buildValidateMixinOutput(mode, [
+                {
+                    source: {
+                        kind: "inline",
+                        label: "<inline>"
+                    },
+                    result: singleResult
                 }
-                // 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 (mode === "path") {
+            const resolvedPath = this.resolveMixinInputPath(sourceInput.path, "path");
+            const singleResult = await this.validateMixinSingle({
+                ...sharedInput,
+                sourcePath: sourceInput.path
+            });
+            return this.buildValidateMixinOutput(mode, [
+                {
+                    source: {
+                        kind: "path",
+                        label: resolvedPath,
+                        path: resolvedPath
+                    },
+                    result: singleResult
                 }
-            }
-            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);
+        if (mode === "paths") {
+            return this.validateMixinMany(mode, sourceInput.paths.map((path) => ({
+                source: {
+                    kind: "path",
+                    label: this.resolveMixinInputPath(path, "path"),
+                    path: this.resolveMixinInputPath(path, "path")
+                },
+                sourcePath: path
+            })), input);
+        }
+        const configSources = await this.resolveMixinConfigSources(input);
+        if (configSources.length === 0) {
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: "Mixin config(s) contain no mixin class entries."
+            });
         }
+        return this.validateMixinMany(mode, configSources.map((entry) => ({
+            source: {
+                kind: "config",
+                label: entry.sourcePath,
+                path: entry.sourcePath,
+                configPath: entry.configPath
+            },
+            sourcePath: entry.sourcePath
+        })), input);
+    }
+    async validateMixinSingle(input) {
         let version = input.version.trim();
         if (!version) {
             throw createError({ code: ERROR_CODES.INVALID_INPUT, message: "version must be non-empty." });
@@ -2489,51 +2512,51 @@ export class SourceService {
                     }
                 }
             }
-            let officialName = resolvedClassName;
-            if (requestedMapping !== "official") {
+            let obfuscatedName = resolvedClassName;
+            if (requestedMapping !== "obfuscated") {
                 try {
                     const mapped = await this.mappingService.findMapping({
                         version,
                         kind: "class",
                         name: resolvedClassName,
                         sourceMapping: requestedMapping,
-                        targetMapping: "official",
+                        targetMapping: "obfuscated",
                         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 });
+                        obfuscatedName = mapped.resolvedSymbol.name;
+                        resolutionTrace?.push({ target: target.className, step: "mapping", input: resolvedClassName, output: obfuscatedName, success: true });
                     }
                     else {
-                        warnings.push(`Could not map class "${resolvedClassName}" from ${requestedMapping} to official; using "${officialName}" for lookup.`);
+                        warnings.push(`Could not map class "${resolvedClassName}" from ${requestedMapping} to obfuscated; using "${obfuscatedName}" for lookup.`);
                         mappingFailedTargets.add(target.className);
-                        resolutionTrace?.push({ target: target.className, step: "mapping", input: resolvedClassName, output: officialName, success: false, detail: "No mapping found" });
+                        resolutionTrace?.push({ target: target.className, step: "mapping", input: resolvedClassName, output: obfuscatedName, success: false, detail: "No mapping found" });
                     }
                 }
                 catch (mapErr) {
-                    warnings.push(`Mapping lookup failed for class "${resolvedClassName}"; using "${officialName}" for lookup.`);
+                    warnings.push(`Mapping lookup failed for class "${resolvedClassName}"; using "${obfuscatedName}" 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) });
+                    resolutionTrace?.push({ target: target.className, step: "mapping", input: resolvedClassName, output: obfuscatedName, success: false, detail: mapErr instanceof Error ? mapErr.message : String(mapErr) });
                 }
             }
             try {
                 const sig = await this.explorerService.getSignature({
-                    fqn: officialName,
+                    fqn: obfuscatedName,
                     jarPath,
                     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 });
+                resolutionTrace?.push({ target: target.className, step: "signature", input: obfuscatedName, 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") {
+                if (requestedMapping !== "obfuscated") {
                     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)
+                            this.remapSignatureMembers(sig.constructors, "method", version, "obfuscated", requestedMapping, input.sourcePriority, warnings),
+                            this.remapSignatureMembers(sig.methods, "method", version, "obfuscated", requestedMapping, input.sourcePriority, warnings),
+                            this.remapSignatureMembers(sig.fields, "field", version, "obfuscated", requestedMapping, input.sourcePriority, warnings)
                         ]);
                         constructors = ctorResult.members;
                         methods = methodResult.members;
@@ -2555,9 +2578,9 @@ export class SourceService {
                         }
                     }
                     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) });
+                        warnings.push(`Member remapping failed for "${resolvedClassName}"; falling back to obfuscated names. Member names shown may be in the obfuscated runtime namespace.`);
+                        mappingApplied = "obfuscated";
+                        resolutionTrace?.push({ target: target.className, step: "remap", input: resolvedClassName, output: "obfuscated fallback", success: false, detail: remapErr instanceof Error ? remapErr.message : String(remapErr) });
                     }
                 }
                 targetMembers.set(target.className, {
@@ -2568,9 +2591,9 @@ export class SourceService {
                 });
             }
             catch (sigErr) {
-                warnings.push(`Could not load signature for class "${resolvedClassName}" (official: "${officialName}").`);
+                warnings.push(`Could not load signature for class "${resolvedClassName}" (obfuscated: "${obfuscatedName}").`);
                 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) });
+                resolutionTrace?.push({ target: target.className, step: "signature", input: obfuscatedName, 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({
@@ -2617,8 +2640,8 @@ export class SourceService {
         }
         // Build mapping chain description
         const mappingChain = [];
-        if (requestedMapping !== "official") {
-            mappingChain.push(`${requestedMapping} → official`);
+        if (requestedMapping !== "obfuscated") {
+            mappingChain.push(`${requestedMapping} → obfuscated`);
             if (mappingApplied !== requestedMapping) {
                 mappingChain.push(`fallback to ${mappingApplied}`);
             }
@@ -2713,45 +2736,123 @@ export class SourceService {
         }
         return result;
     }
-    async validateMixinBatch(input) {
-        const paths = input.sourcePaths;
+    resolveMixinInputPath(rawPath, fieldName) {
+        const normalizedPath = normalizePathForHost(rawPath, undefined, fieldName);
+        return isAbsolute(normalizedPath)
+            ? normalizedPath
+            : resolvePath(process.cwd(), normalizedPath);
+    }
+    async resolveMixinConfigSources(input) {
+        if (input.input.mode !== "config") {
+            return [];
+        }
+        const results = [];
+        for (const rawConfigPath of input.input.configPaths) {
+            const resolvedConfigPath = this.resolveMixinInputPath(rawConfigPath, "configPath");
+            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 mixin config "${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;
+            }
+            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 {
+                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));
+                }));
+                sourceRootCandidates = detected.length > 0 ? detected : ["src/main/java"];
+            }
+            for (const cls of classNames) {
+                const fqcn = pkg ? `${pkg}.${cls}` : cls;
+                const relativePath = fqcn.replace(/\./g, "/") + ".java";
+                let sourcePath = resolvePath(projectBase, sourceRootCandidates[0], relativePath);
+                for (const root of sourceRootCandidates) {
+                    const candidate = resolvePath(projectBase, root, relativePath);
+                    if (existsSync(candidate)) {
+                        sourcePath = candidate;
+                        break;
+                    }
+                }
+                results.push({
+                    sourcePath,
+                    configPath: resolvedConfigPath
+                });
+            }
+        }
+        return results;
+    }
+    async validateMixinMany(mode, entries, input) {
         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) {
+        const { input: _discardedInput, ...sharedInput } = input;
+        for (const entry of entries) {
             try {
-                const singleResult = await this.validateMixin({
-                    ...input,
-                    sourcePaths: undefined,
-                    source: undefined,
-                    sourcePath: sp,
+                const singleResult = await this.validateMixinSingle({
+                    ...sharedInput,
+                    sourcePath: entry.sourcePath,
                     warningMode: batchWarningMode
                 });
-                results.push({ sourcePath: sp, result: singleResult });
-                if (singleResult.valid) {
-                    validCount++;
-                }
-                else {
-                    invalidCount++;
-                }
+                results.push({
+                    source: entry.source,
+                    result: singleResult
+                });
             }
             catch (err) {
                 results.push({
-                    sourcePath: sp,
+                    source: entry.source,
                     error: err instanceof Error ? err.message : String(err)
                 });
-                errorCount++;
             }
         }
-        // Build issueSummary: aggregate issues across all results by (kind, confidence, category)
+        return this.buildValidateMixinOutput(mode, results);
+    }
+    buildValidateMixinOutput(mode, results) {
+        let valid = 0;
+        let invalid = 0;
+        let processingErrors = 0;
+        let totalValidationErrors = 0;
+        let totalValidationWarnings = 0;
+        const warningSet = new Set();
         const issueGroupMap = new Map();
-        for (const r of results) {
-            if (!r.result)
+        for (const entry of results) {
+            if (!entry.result) {
+                processingErrors++;
                 continue;
-            for (const issue of r.result.issues) {
+            }
+            if (entry.result.valid) {
+                valid++;
+            }
+            else {
+                invalid++;
+            }
+            totalValidationErrors += entry.result.summary.errors;
+            totalValidationWarnings += entry.result.summary.warnings;
+            for (const warning of entry.result.warnings) {
+                warningSet.add(warning);
+            }
+            for (const issue of entry.result.issues) {
                 const key = `${issue.kind}\0${issue.confidence ?? "unknown"}\0${issue.category ?? "validation"}`;
                 const existing = issueGroupMap.get(key);
                 if (existing) {
@@ -2771,39 +2872,26 @@ export class SourceService {
                 }
             }
         }
-        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;
+        const issueSummary = issueGroupMap.size > 0 ? [...issueGroupMap.values()] : undefined;
+        const toolHealth = results.find((entry) => entry.result?.toolHealth)?.result?.toolHealth;
+        const confidenceScores = results
+            .map((entry) => entry.result?.confidenceScore)
+            .filter((score) => score != null);
         return {
+            mode,
             results,
             summary: {
-                total: paths.length,
-                valid: validCount,
-                invalid: invalidCount,
-                errors: errorCount,
-                processingErrors: errorCount,
+                total: results.length,
+                valid,
+                invalid,
+                processingErrors,
                 totalValidationErrors,
-                totalValidationWarnings,
-                confidenceScore: batchConfidenceScore
+                totalValidationWarnings
             },
             issueSummary,
-            toolHealth: sharedHealth
+            toolHealth,
+            confidenceScore: confidenceScores.length > 0 ? Math.min(...confidenceScores) : undefined,
+            warnings: [...warningSet]
         };
     }
     async validateAccessWidener(input) {
@@ -2828,7 +2916,7 @@ export class SourceService {
         if (overrideMapping && headerNamespace && overrideMapping !== headerNamespace) {
             warnings.push(`Using mapping override "${overrideMapping}" instead of header namespace "${headerNamespaceRaw}".`);
         }
-        const needsMapping = awNamespace !== "official";
+        const needsMapping = awNamespace !== "obfuscated";
         // Collect unique class FQNs from entries
         const classFqns = new Set();
         for (const entry of parsed.entries) {
@@ -2837,7 +2925,7 @@ export class SourceService {
         }
         const membersByClass = new Map();
         for (const fqn of classFqns) {
-            let officialFqn = fqn;
+            let obfuscatedFqn = fqn;
             if (needsMapping) {
                 try {
                     const mapped = await this.mappingService.findMapping({
@@ -2845,14 +2933,14 @@ export class SourceService {
                         kind: "class",
                         name: fqn,
                         sourceMapping: awNamespace,
-                        targetMapping: "official",
+                        targetMapping: "obfuscated",
                         sourcePriority: input.sourcePriority
                     });
                     if (mapped.resolved && mapped.resolvedSymbol) {
-                        officialFqn = mapped.resolvedSymbol.name;
+                        obfuscatedFqn = mapped.resolvedSymbol.name;
                     }
                     else {
-                        warnings.push(`Could not map class "${fqn}" from ${awNamespace} to official.`);
+                        warnings.push(`Could not map class "${fqn}" from ${awNamespace} to obfuscated.`);
                     }
                 }
                 catch {
@@ -2861,7 +2949,7 @@ export class SourceService {
             }
             try {
                 const sig = await this.explorerService.getSignature({
-                    fqn: officialFqn,
+                    fqn: obfuscatedFqn,
                     jarPath,
                     access: "all"
                 });
@@ -2874,7 +2962,7 @@ export class SourceService {
                 });
             }
             catch {
-                warnings.push(`Could not load signature for class "${officialFqn}".`);
+                warnings.push(`Could not load signature for class "${obfuscatedFqn}".`);
             }
         }
         return validateParsedAccessWidener(parsed, membersByClass, warnings);
@@ -2915,7 +3003,7 @@ export class SourceService {
                 },
                 indexedAt: currentMeta.indexedAt,
                 durationMs: 0,
-                mappingApplied: artifact.mappingApplied ?? "official"
+                mappingApplied: artifact.mappingApplied ?? "obfuscated"
             };
         }
         const resolved = this.toResolvedArtifact(artifact);
@@ -2932,33 +3020,16 @@ export class SourceService {
             },
             indexedAt: rebuilt.indexedAt,
             durationMs: rebuilt.indexDurationMs,
-            mappingApplied: artifact.mappingApplied ?? "official"
+            mappingApplied: artifact.mappingApplied ?? "obfuscated"
         };
     }
-    searchSymbolIntent(artifactId, query, match, scope, snippetWindow, regexPattern, onHit) {
+    searchSymbolIntent(artifactId, query, match, scope, regexPattern, onHit) {
         const matchedSymbols = this.findSymbolHits(artifactId, query, match, scope, regexPattern);
-        const filePaths = [...new Set(matchedSymbols.map((item) => item.symbol.filePath))];
-        const rows = this.filesRepo.getFileContentsByPaths(artifactId, filePaths);
-        this.metrics.recordSearchDbRoundtrip();
-        this.metrics.recordSearchRowsScanned(rows.length);
-        const rowsByPath = new Map(rows.map((row) => [row.filePath, row]));
         for (const item of matchedSymbols) {
-            const row = rowsByPath.get(item.symbol.filePath);
-            const snippet = row
-                ? toContextSnippet(row.content, item.symbol.line, snippetWindow.before, snippetWindow.after, true)
-                : {
-                    startLine: item.symbol.line,
-                    endLine: item.symbol.line,
-                    snippet: "",
-                    truncated: false
-                };
             onHit({
                 filePath: item.symbol.filePath,
                 score: item.score,
                 matchedIn: "symbol",
-                startLine: snippet.startLine,
-                endLine: snippet.endLine,
-                snippet: snippet.snippet,
                 reasonCodes: [`symbol_${match}`],
                 symbol: {
                     symbolKind: item.symbol.symbolKind,
@@ -2969,7 +3040,7 @@ export class SourceService {
             });
         }
     }
-    searchTextIntentIndexed(artifactId, query, match, scope, includeDefinition, snippetWindow, onHit) {
+    searchTextIntentIndexed(artifactId, query, match, scope, onHit) {
         const candidateLimit = this.indexedCandidateLimitForMatch(match);
         const indexed = this.filesRepo.searchFileCandidates(artifactId, {
             query,
@@ -2998,45 +3069,21 @@ export class SourceService {
             if (contentIndex < 0) {
                 continue;
             }
-            const line = indexToLine(candidate.content, contentIndex);
             candidateRows.push({
                 filePath: candidate.filePath,
-                content: candidate.content,
-                line,
                 contentIndex
             });
         }
-        const needSymbols = includeDefinition || !!scope?.symbolKind;
-        const symbolsByFile = needSymbols
-            ? this.symbolsRepo.listSymbolsForFiles(artifactId, candidateRows.map((candidate) => candidate.filePath), scope?.symbolKind)
-            : new Map();
-        if (needSymbols) {
-            this.metrics.recordSearchDbRoundtrip();
-            this.metrics.recordSearchRowsScanned([...symbolsByFile.values()].reduce((acc, symbols) => acc + symbols.length, 0));
-        }
         for (const candidate of candidateRows) {
-            // When symbolKind filter is set, skip files that have no symbols of that kind
-            if (scope?.symbolKind && !symbolsByFile.has(candidate.filePath)) {
-                continue;
-            }
-            const snippet = toContextSnippet(candidate.content, candidate.line, snippetWindow.before, snippetWindow.after, true);
-            const definition = includeDefinition
-                ? this.findNearestSymbolFromList(symbolsByFile.get(candidate.filePath) ?? [], candidate.line)
-                : undefined;
-            const resolvedSymbol = definition ? lineToSymbol(definition) : undefined;
             onHit({
                 filePath: candidate.filePath,
-                score: scoreTextMatch(match, candidate.contentIndex) + (resolvedSymbol ? 20 : 0),
+                score: scoreTextMatch(match, candidate.contentIndex),
                 matchedIn: "content",
-                startLine: snippet.startLine,
-                endLine: snippet.endLine,
-                snippet: snippet.snippet,
-                reasonCodes: ["content_match", `text_${match}`, "indexed"],
-                symbol: resolvedSymbol
+                reasonCodes: ["content_match", `text_${match}`, "indexed"]
             });
         }
     }
-    searchPathIntentIndexed(artifactId, query, match, scope, includeDefinition, snippetWindow, onHit) {
+    searchPathIntentIndexed(artifactId, query, match, scope, onHit) {
         const candidateLimit = this.indexedCandidateLimitForMatch(match);
         const indexed = this.filesRepo.searchFileCandidates(artifactId, {
             query,
@@ -3071,59 +3118,22 @@ export class SourceService {
                 pathIndex
             });
         }
-        const candidateContentRows = this.filesRepo.getFileContentsByPaths(artifactId, candidateRows.map((candidate) => candidate.filePath));
-        this.metrics.recordSearchDbRoundtrip();
-        this.metrics.recordSearchRowsScanned(candidateContentRows.length);
-        const contentByPath = new Map(candidateContentRows.map((row) => [row.filePath, row.content]));
-        const needSymbols = includeDefinition || !!scope?.symbolKind;
-        const symbolsByFile = needSymbols
-            ? this.symbolsRepo.listSymbolsForFiles(artifactId, candidateRows.map((candidate) => candidate.filePath), scope?.symbolKind)
-            : new Map();
-        if (needSymbols) {
-            this.metrics.recordSearchDbRoundtrip();
-            this.metrics.recordSearchRowsScanned([...symbolsByFile.values()].reduce((acc, symbols) => acc + symbols.length, 0));
-        }
         for (const candidate of candidateRows) {
-            const content = contentByPath.get(candidate.filePath);
-            if (!content) {
-                continue;
-            }
-            // When symbolKind filter is set, skip files that have no symbols of that kind
-            if (scope?.symbolKind && !symbolsByFile.has(candidate.filePath)) {
-                continue;
-            }
-            const definition = includeDefinition
-                ? this.findNearestSymbolFromList(symbolsByFile.get(candidate.filePath) ?? [], 1)
-                : undefined;
-            const centerLine = definition?.line ?? 1;
-            const snippet = toContextSnippet(content, centerLine, snippetWindow.before, snippetWindow.after, true);
-            const resolvedSymbol = definition ? lineToSymbol(definition) : undefined;
             onHit({
                 filePath: candidate.filePath,
-                score: scorePathMatch(match, candidate.pathIndex) + (resolvedSymbol ? 10 : 0),
+                score: scorePathMatch(match, candidate.pathIndex),
                 matchedIn: "path",
-                startLine: snippet.startLine,
-                endLine: snippet.endLine,
-                snippet: snippet.snippet,
-                reasonCodes: ["path_match", `path_${match}`, "indexed"],
-                symbol: resolvedSymbol
+                reasonCodes: ["path_match", `path_${match}`, "indexed"]
             });
         }
     }
-    searchTextIntent(artifactId, query, match, scope, includeDefinition, snippetWindow, regexPattern, onHit) {
+    searchTextIntent(artifactId, query, match, scope, regexPattern, onHit) {
         const filePaths = this.loadScopedFilePaths(artifactId, scope);
         const pageSize = Math.max(1, this.config.searchScanPageSize ?? 250);
         for (const chunk of chunkArray(filePaths, pageSize)) {
             const rows = this.filesRepo.getFileContentsByPaths(artifactId, chunk);
             this.metrics.recordSearchDbRoundtrip();
             this.metrics.recordSearchRowsScanned(rows.length);
-            const symbolsByFile = includeDefinition
-                ? this.symbolsRepo.listSymbolsForFiles(artifactId, rows.map((row) => row.filePath), scope?.symbolKind)
-                : new Map();
-            if (includeDefinition) {
-                this.metrics.recordSearchDbRoundtrip();
-                this.metrics.recordSearchRowsScanned([...symbolsByFile.values()].reduce((acc, symbols) => acc + symbols.length, 0));
-            }
             for (const row of rows) {
                 const contentIndex = match === "regex"
                     ? matchRegexIndex(row.content, regexPattern)
@@ -3131,26 +3141,16 @@ export class SourceService {
                 if (contentIndex < 0) {
                     continue;
                 }
-                const line = indexToLine(row.content, contentIndex);
-                const snippet = toContextSnippet(row.content, line, snippetWindow.before, snippetWindow.after, true);
-                const definition = includeDefinition
-                    ? this.findNearestSymbolFromList(symbolsByFile.get(row.filePath) ?? [], line)
-                    : undefined;
-                const resolvedSymbol = definition ? lineToSymbol(definition) : undefined;
                 onHit({
                     filePath: row.filePath,
-                    score: scoreTextMatch(match, contentIndex) + (resolvedSymbol ? 20 : 0),
+                    score: scoreTextMatch(match, contentIndex),
                     matchedIn: "content",
-                    startLine: snippet.startLine,
-                    endLine: snippet.endLine,
-                    snippet: snippet.snippet,
-                    reasonCodes: ["content_match", `text_${match}`],
-                    symbol: resolvedSymbol
+                    reasonCodes: ["content_match", `text_${match}`]
                 });
             }
         }
     }
-    searchPathIntent(artifactId, query, match, scope, includeDefinition, snippetWindow, regexPattern, onHit) {
+    searchPathIntent(artifactId, query, match, scope, regexPattern, onHit) {
         const filePaths = this.loadScopedFilePaths(artifactId, scope);
         const matching = filePaths.flatMap((filePath) => {
             const pathIndex = match === "regex"
@@ -3163,37 +3163,12 @@ export class SourceService {
         });
         const pageSize = Math.max(1, this.config.searchScanPageSize ?? 250);
         for (const chunk of chunkArray(matching, pageSize)) {
-            const rows = this.filesRepo.getFileContentsByPaths(artifactId, chunk.map((item) => item.filePath));
-            this.metrics.recordSearchDbRoundtrip();
-            this.metrics.recordSearchRowsScanned(rows.length);
-            const contentByPath = new Map(rows.map((row) => [row.filePath, row.content]));
-            const symbolsByFile = includeDefinition
-                ? this.symbolsRepo.listSymbolsForFiles(artifactId, chunk.map((item) => item.filePath), scope?.symbolKind)
-                : new Map();
-            if (includeDefinition) {
-                this.metrics.recordSearchDbRoundtrip();
-                this.metrics.recordSearchRowsScanned([...symbolsByFile.values()].reduce((acc, symbols) => acc + symbols.length, 0));
-            }
             for (const candidate of chunk) {
-                const content = contentByPath.get(candidate.filePath);
-                if (!content) {
-                    continue;
-                }
-                const definition = includeDefinition
-                    ? this.findNearestSymbolFromList(symbolsByFile.get(candidate.filePath) ?? [], 1)
-                    : undefined;
-                const centerLine = definition?.line ?? 1;
-                const snippet = toContextSnippet(content, centerLine, snippetWindow.before, snippetWindow.after, true);
-                const resolvedSymbol = definition ? lineToSymbol(definition) : undefined;
                 onHit({
                     filePath: candidate.filePath,
-                    score: scorePathMatch(match, candidate.pathIndex) + (resolvedSymbol ? 10 : 0),
+                    score: scorePathMatch(match, candidate.pathIndex),
                     matchedIn: "path",
-                    startLine: snippet.startLine,
-                    endLine: snippet.endLine,
-                    snippet: snippet.snippet,
-                    reasonCodes: ["path_match", `path_${match}`],
-                    symbol: resolvedSymbol
+                    reasonCodes: ["path_match", `path_${match}`]
                 });
             }
         }
@@ -3262,13 +3237,6 @@ export class SourceService {
     }
     loadScopedFilePaths(artifactId, scope) {
         const glob = scope?.fileGlob ? buildGlobRegex(normalizePathStyle(scope.fileGlob)) : undefined;
-        const scopedFilesBySymbolKind = scope?.symbolKind
-            ? new Set(this.symbolsRepo.listDistinctFilePathsByKind(artifactId, scope.symbolKind))
-            : undefined;
-        if (scopedFilesBySymbolKind) {
-            this.metrics.recordSearchDbRoundtrip();
-            this.metrics.recordSearchRowsScanned(scopedFilesBySymbolKind.size);
-        }
         const result = [];
         let cursor = undefined;
         const pageSize = Math.max(1, this.config.searchScanPageSize ?? 250);
@@ -3283,9 +3251,6 @@ export class SourceService {
                 if (glob && !glob.test(filePath)) {
                     continue;
                 }
-                if (scopedFilesBySymbolKind && !scopedFilesBySymbolKind.has(filePath)) {
-                    continue;
-                }
                 result.push(filePath);
             }
             if (!page.nextCursor) {
@@ -3365,141 +3330,27 @@ export class SourceService {
         }
         return undefined;
     }
-    findNearestSymbolForLine(artifactId, filePath, line, symbolKind) {
-        const symbols = this.symbolsRepo
-            .listSymbolsForFile(artifactId, filePath)
-            .filter((symbol) => (symbolKind ? symbol.symbolKind === symbolKind : true));
-        return this.findNearestSymbolFromList(symbols, line);
-    }
-    findNearestSymbolFromList(symbols, line) {
-        let best;
-        for (const symbol of symbols) {
-            if (symbol.line > line) {
-                continue;
-            }
-            if (!best || symbol.line >= best.line) {
-                best = symbol;
-            }
-        }
-        return best ?? symbols[0];
-    }
-    buildOneHopRelations(artifactId, roots, maxRelations) {
-        if (roots.length === 0 || maxRelations <= 0) {
-            return [];
+    async resolveBinaryFallbackArtifact(input) {
+        const binaryJarPath = normalizeOptionalString(input.binaryJarPath);
+        if (!binaryJarPath) {
+            return undefined;
         }
-        const rootRows = this.filesRepo.getFileContentsByPaths(artifactId, roots.map((root) => root.filePath));
-        this.metrics.recordSearchDbRoundtrip();
-        this.metrics.recordSearchRowsScanned(rootRows.length);
-        const rootRowsByPath = new Map(rootRows.map((row) => [row.filePath, row]));
-        const rootTokens = roots.map((root) => {
-            const contentRow = rootRowsByPath.get(root.filePath);
-            if (!contentRow) {
-                return {
-                    root,
-                    calls: [],
-                    types: [],
-                    imports: []
-                };
-            }
-            const aroundRoot = toContextSnippet(contentRow.content, root.line, 2, 3, false).snippet;
-            return {
-                root,
-                calls: Array.from(aroundRoot.matchAll(/\b([A-Za-z_$][\w$]*)\s*\(/g))
-                    .map((match) => match[1])
-                    .filter((token) => Boolean(token)),
-                types: Array.from(aroundRoot.matchAll(/\b([A-Z][A-Za-z0-9_$]*)\b/g))
-                    .map((match) => match[1])
-                    .filter((token) => Boolean(token)),
-                imports: Array.from(aroundRoot.matchAll(/import\s+([\w.$]+);/g))
-                    .map((match) => match[1]?.split(".").at(-1))
-                    .filter((token) => Boolean(token))
-            };
-        });
-        const tokenSet = new Set();
-        for (const entry of rootTokens) {
-            for (const token of entry.calls) {
-                tokenSet.add(toLower(token));
-            }
-            for (const token of entry.types) {
-                tokenSet.add(toLower(token));
-            }
-            for (const token of entry.imports) {
-                tokenSet.add(toLower(token));
-            }
+        try {
+            const fallbackResolved = await resolveSourceTargetInternal({ kind: "jar", value: binaryJarPath }, { allowDecompile: true, preferBinaryOnly: true }, this.config);
+            fallbackResolved.version = fallbackResolved.version ?? input.version;
+            fallbackResolved.coordinate = fallbackResolved.coordinate ?? input.coordinate;
+            fallbackResolved.requestedMapping = input.requestedMapping;
+            fallbackResolved.mappingApplied = input.mappingApplied;
+            fallbackResolved.provenance = input.provenance;
+            fallbackResolved.qualityFlags = [
+                ...new Set([...(fallbackResolved.qualityFlags ?? []), ...input.qualityFlags, "binary-fallback"])
+            ];
+            await this.ingestIfNeeded(fallbackResolved);
+            return fallbackResolved;
         }
-        const matchedSymbols = this.symbolsRepo
-            .findBySymbolNames(artifactId, [...tokenSet])
-            .filter((symbol) => isSymbolKind(symbol.symbolKind));
-        this.metrics.recordSearchDbRoundtrip();
-        this.metrics.recordSearchRowsScanned(matchedSymbols.length);
-        const symbolMap = new Map();
-        for (const symbol of matchedSymbols) {
-            const key = toLower(symbol.symbolName);
-            const bucket = symbolMap.get(key) ?? [];
-            bucket.push(symbol);
-            symbolMap.set(key, bucket);
-        }
-        const dedupe = new Set();
-        const relations = [];
-        for (const entry of rootTokens) {
-            const root = entry.root;
-            const attach = (token, relationKind) => {
-                const matches = symbolMap.get(toLower(token)) ?? [];
-                for (const target of matches) {
-                    if (!isSymbolKind(target.symbolKind)) {
-                        continue;
-                    }
-                    if (target.filePath === root.filePath &&
-                        target.line === root.line &&
-                        target.symbolName === root.symbolName &&
-                        target.symbolKind === root.symbolKind) {
-                        continue;
-                    }
-                    const key = `${root.symbolKind}:${root.symbolName}:${root.filePath}:${root.line}->${target.symbolKind}:${target.symbolName}:${target.filePath}:${target.line}:${relationKind}`;
-                    if (dedupe.has(key)) {
-                        continue;
-                    }
-                    dedupe.add(key);
-                    relations.push({
-                        fromSymbol: {
-                            symbolKind: root.symbolKind,
-                            symbolName: root.symbolName,
-                            filePath: root.filePath,
-                            line: root.line
-                        },
-                        toSymbol: {
-                            symbolKind: target.symbolKind,
-                            symbolName: target.symbolName,
-                            filePath: target.filePath,
-                            line: target.line
-                        },
-                        relation: relationKind
-                    });
-                    if (relations.length >= maxRelations) {
-                        return;
-                    }
-                }
-            };
-            for (const token of entry.calls) {
-                attach(token, "calls");
-                if (relations.length >= maxRelations) {
-                    return relations;
-                }
-            }
-            for (const token of entry.types) {
-                attach(token, "uses-type");
-                if (relations.length >= maxRelations) {
-                    return relations;
-                }
-            }
-            for (const token of entry.imports) {
-                attach(token, "imports");
-                if (relations.length >= maxRelations) {
-                    return relations;
-                }
-            }
+        catch {
+            return undefined;
         }
-        return relations;
     }
     buildProvenance(input) {
         const provenance = {
@@ -3551,31 +3402,107 @@ export class SourceService {
             transformChain
         };
     }
-    async resolveToOfficialClassName(className, version, mapping, sourcePriority, warnings) {
-        if (mapping === "official") {
-            return className;
+    async resolveClassNameForLookup(input) {
+        if (input.sourceMapping === input.targetMapping) {
+            return input.className;
+        }
+        if (!input.version) {
+            input.warnings.push(`Could not map class "${input.className}" from ${input.sourceMapping} to ${input.targetMapping} for ${input.context} because version is unavailable.`);
+            return input.className;
         }
         try {
             const mapped = await this.mappingService.findMapping({
-                version,
+                version: input.version,
                 kind: "class",
-                name: className,
-                sourceMapping: mapping,
-                targetMapping: "official",
-                sourcePriority
+                name: input.className,
+                sourceMapping: input.sourceMapping,
+                targetMapping: input.targetMapping,
+                sourcePriority: input.sourcePriority
             });
             if (mapped.resolved && mapped.resolvedSymbol) {
                 return mapped.resolvedSymbol.name;
             }
-            warnings.push(`Could not map class "${className}" from ${mapping} to official.`);
+            input.warnings.push(`Could not map class "${input.className}" from ${input.sourceMapping} to ${input.targetMapping} for ${input.context}.`);
         }
         catch {
-            warnings.push(`Mapping lookup failed for class "${className}".`);
+            input.warnings.push(`Mapping lookup failed for class "${input.className}" while preparing ${input.context} in ${input.targetMapping}.`);
+        }
+        return input.className;
+    }
+    buildClassSourceNotFoundError(input) {
+        const simpleName = input.className.split(/[.$]/).at(-1) ?? input.className;
+        const details = {
+            artifactId: input.artifactId,
+            className: input.className,
+            mapping: input.mappingApplied,
+            qualityFlags: input.qualityFlags,
+            ...(input.lookupClassName !== input.className ? { lookupClassName: input.lookupClassName } : {}),
+            ...(input.filePath ? { filePath: input.filePath } : {}),
+            ...(input.scope ? { scope: input.scope } : {}),
+            ...(input.targetKind ? { targetKind: input.targetKind } : {}),
+            ...(input.targetValue ? { targetValue: input.targetValue } : {}),
+            ...(input.attemptedBinaryFallback ? { binaryFallbackAttempted: true } : {})
+        };
+        let nextAction = `Use find-class to resolve the correct fully-qualified name for "${simpleName}".`;
+        let suggestedCall = {
+            tool: "find-class",
+            params: { className: simpleName, artifactId: input.artifactId }
+        };
+        if (input.targetKind === "version" && input.scope && input.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 (input.targetKind === "version" && input.scope && input.scope !== "merged" && input.projectPath) {
+            nextAction += ` The class may exist in merged sources; retry with scope: "merged".`;
+        }
+        if (hasPartialNetMinecraftCoverage(input.qualityFlags)) {
+            nextAction =
+                `Resolved source coverage does not include net.minecraft for "${input.className}",` +
+                    (input.attemptedBinaryFallback
+                        ? " and binary fallback did not produce source for that class."
+                        : " and a binary fallback has not produced source for that class.") +
+                    " Use get-class-api-matrix or find-mapping instead of find-class for vanilla API discovery.";
+            if (input.version) {
+                suggestedCall = {
+                    tool: "get-class-api-matrix",
+                    params: {
+                        version: input.version,
+                        className: input.className,
+                        classNameMapping: input.requestedMapping
+                    }
+                };
+            }
+            else {
+                suggestedCall = {
+                    tool: "find-class",
+                    params: { className: simpleName, artifactId: input.artifactId }
+                };
+            }
+        }
+        if (input.mappingApplied === "obfuscated" && looksLikeDeobfuscatedClassName(input.className)) {
+            nextAction += ` ${obfuscatedNamespaceHint(input.className)}`;
         }
-        return className;
+        details.nextAction = nextAction;
+        details.suggestedCall = suggestedCall;
+        return createError({
+            code: ERROR_CODES.CLASS_NOT_FOUND,
+            message: `Source for class "${input.className}" was not found.`,
+            details
+        });
+    }
+    async resolveToObfuscatedClassName(className, version, mapping, sourcePriority, warnings) {
+        return this.resolveClassNameForLookup({
+            className,
+            version,
+            sourceMapping: mapping,
+            targetMapping: "obfuscated",
+            sourcePriority,
+            warnings,
+            context: "bytecode lookup"
+        });
     }
-    async resolveToOfficialMemberName(name, ownerInSourceMapping, descriptor, kind, version, mapping, sourcePriority, warnings) {
-        if (mapping === "official") {
+    async resolveToObfuscatedMemberName(name, ownerInSourceMapping, descriptor, kind, version, mapping, sourcePriority, warnings) {
+        if (mapping === "obfuscated") {
             return {
                 name,
                 descriptor: kind === "method" ? descriptor : undefined
@@ -3589,7 +3516,7 @@ export class SourceService {
                 owner: ownerInSourceMapping,
                 descriptor,
                 sourceMapping: mapping,
-                targetMapping: "official",
+                targetMapping: "obfuscated",
                 sourcePriority
             });
             if (mapped.resolved && mapped.resolvedSymbol) {
@@ -3598,7 +3525,7 @@ export class SourceService {
                     descriptor: kind === "method" ? mapped.resolvedSymbol.descriptor ?? descriptor : undefined
                 };
             }
-            warnings.push(`Could not map ${kind} "${name}" from ${mapping} to official.`);
+            warnings.push(`Could not map ${kind} "${name}" from ${mapping} to obfuscated.`);
         }
         catch {
             warnings.push(`Mapping lookup failed for ${kind} "${name}".`);
@@ -3608,9 +3535,9 @@ export class SourceService {
             descriptor: kind === "method" ? descriptor : undefined
         };
     }
-    async remapSignatureMembers(members, kind, version, mapping, sourcePriority, warnings) {
+    async remapSignatureMembers(members, kind, version, sourceMapping, targetMapping, sourcePriority, warnings) {
         const failedNames = new Set();
-        if (mapping === "official") {
+        if (sourceMapping === targetMapping) {
             return { members, failedNames };
         }
         // Build deduplicated lookup tables for member names and owner FQNs
@@ -3619,35 +3546,35 @@ export class SourceService {
         for (const member of members) {
             const memberKey = `${member.ownerFqn}\0${member.name}\0${member.jvmDescriptor}`;
             if (!memberKeyToRemapped.has(memberKey)) {
-                memberKeyToRemapped.set(memberKey, member.name); // default = official name
+                memberKeyToRemapped.set(memberKey, member.name); // default = obfuscated name
             }
             if (!ownerToRemapped.has(member.ownerFqn)) {
-                ownerToRemapped.set(member.ownerFqn, member.ownerFqn); // default = official FQN
+                ownerToRemapped.set(member.ownerFqn, member.ownerFqn); // default = obfuscated FQN
             }
         }
         // Phase 1: Remap owner FQNs first (needed for member disambiguation)
         const ownerEntries = [...ownerToRemapped.entries()];
-        await Promise.all(ownerEntries.map(async ([officialFqn]) => {
+        await Promise.all(ownerEntries.map(async ([obfuscatedFqn]) => {
             try {
                 const mapped = await this.mappingService.findMapping({
                     version,
                     kind: "class",
-                    name: officialFqn,
-                    sourceMapping: "official",
-                    targetMapping: mapping,
+                    name: obfuscatedFqn,
+                    sourceMapping,
+                    targetMapping,
                     sourcePriority
                 });
                 if (mapped.resolved && mapped.resolvedSymbol) {
-                    ownerToRemapped.set(officialFqn, mapped.resolvedSymbol.name);
+                    ownerToRemapped.set(obfuscatedFqn, mapped.resolvedSymbol.name);
                 }
             }
             catch {
-                // keep official FQN as fallback
+                // keep obfuscated FQN as fallback
             }
         }));
         // Phase 2: Remap member names using resolved owners for disambiguation
         const memberEntries = [...memberKeyToRemapped.entries()];
-        await Promise.all(memberEntries.map(async ([key, _officialName]) => {
+        await Promise.all(memberEntries.map(async ([key, _obfuscatedName]) => {
             const [ownerFqn, name, descriptor] = key.split("\0");
             try {
                 const targetOwner = ownerToRemapped.get(ownerFqn) ?? ownerFqn;
@@ -3657,8 +3584,8 @@ export class SourceService {
                     name,
                     owner: ownerFqn,
                     descriptor: kind === "method" ? descriptor : undefined,
-                    sourceMapping: "official",
-                    targetMapping: mapping,
+                    sourceMapping,
+                    targetMapping,
                     sourcePriority,
                     disambiguation: { ownerHint: targetOwner }
                 });
@@ -3677,17 +3604,17 @@ export class SourceService {
                         }
                     }
                     else {
-                        warnings.push(`Could not remap ${kind} "${name}" to ${mapping}.`);
+                        warnings.push(`Could not remap ${kind} "${name}" from ${sourceMapping} to ${targetMapping}.`);
                         failedNames.add(name);
                     }
                 }
                 else {
-                    warnings.push(`Could not remap ${kind} "${name}" to ${mapping}.`);
+                    warnings.push(`Could not remap ${kind} "${name}" from ${sourceMapping} to ${targetMapping}.`);
                     failedNames.add(name);
                 }
             }
             catch {
-                warnings.push(`Remap failed for ${kind} "${name}".`);
+                warnings.push(`Remap failed for ${kind} "${name}" from ${sourceMapping} to ${targetMapping}.`);
                 failedNames.add(name);
             }
         }));