@adhisang/minecraft-modding-mcp 1.2.1 → 2.1.0

package/dist/source-service.js

@@ -12,7 +12,7 @@ import { parseCoordinate } from "./maven-resolver.js";
 import { MinecraftExplorerService } from "./minecraft-explorer-service.js";
 import { parseMixinSource } from "./mixin-parser.js";
 import { parseAccessWidener } from "./access-widener-parser.js";
-import { validateParsedMixin, validateParsedAccessWidener } from "./mixin-validator.js";
+import { validateParsedMixin, refreshMixinValidationOutcome, validateParsedAccessWidener } from "./mixin-validator.js";
 import { resolveSourceTarget as resolveSourceTargetInternal } from "./source-resolver.js";
 import { applyMappingPipeline } from "./mapping-pipeline-service.js";
 import { MappingService } from "./mapping-service.js";
@@ -34,6 +34,19 @@ import { VersionDiffService } from "./version-diff-service.js";
 import { ModDecompileService } from "./mod-decompile-service.js";
 import { ModSearchService } from "./mod-search-service.js";
 const utf8Decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+const VERSION_TOKEN_REGEX_CACHE = new Map();
+const GLOB_REGEX_CACHE = new Map();
+const MAX_HELPER_REGEX_CACHE = 128;
+function rememberCachedRegex(cache, key, regex) {
+    if (cache.size >= MAX_HELPER_REGEX_CACHE) {
+        const oldestKey = cache.keys().next().value;
+        if (oldestKey) {
+            cache.delete(oldestKey);
+        }
+    }
+    cache.set(key, regex);
+    return regex;
+}
 function truncateUtf8ToMaxBytes(content, maxBytes) {
     const encoded = Buffer.from(content, "utf8");
     if (encoded.length <= maxBytes) {
@@ -51,6 +64,88 @@ function truncateUtf8ToMaxBytes(content, maxBytes) {
     }
     return "";
 }
+function dedupeQualityFlags(qualityFlags) {
+    const seen = new Set();
+    const deduped = [];
+    for (const qualityFlag of qualityFlags) {
+        if (seen.has(qualityFlag)) {
+            continue;
+        }
+        seen.add(qualityFlag);
+        deduped.push(qualityFlag);
+    }
+    return deduped;
+}
+function sameStringArray(left, right) {
+    if (left === right) {
+        return true;
+    }
+    if (!left || !right || left.length !== right.length) {
+        return false;
+    }
+    for (let index = 0; index < left.length; index += 1) {
+        if (left[index] !== right[index]) {
+            return false;
+        }
+    }
+    return true;
+}
+function sameScopeFallback(left, right) {
+    if (left === right) {
+        return true;
+    }
+    if (!left || !right) {
+        return false;
+    }
+    return left.requested === right.requested && left.applied === right.applied && left.reason === right.reason;
+}
+function sameResolutionTrace(left, right) {
+    if (left === right) {
+        return true;
+    }
+    if (!left || !right || left.length !== right.length) {
+        return false;
+    }
+    for (let index = 0; index < left.length; index += 1) {
+        const leftEntry = left[index];
+        const rightEntry = right[index];
+        if (!leftEntry || !rightEntry) {
+            return false;
+        }
+        if (leftEntry.target !== rightEntry.target ||
+            leftEntry.step !== rightEntry.step ||
+            leftEntry.input !== rightEntry.input ||
+            leftEntry.output !== rightEntry.output ||
+            leftEntry.success !== rightEntry.success ||
+            leftEntry.detail !== rightEntry.detail) {
+            return false;
+        }
+    }
+    return true;
+}
+function sameMixinValidationProvenance(left, right) {
+    if (left === right) {
+        return true;
+    }
+    if (!left || !right) {
+        return false;
+    }
+    return (left.version === right.version &&
+        left.jarPath === right.jarPath &&
+        left.requestedMapping === right.requestedMapping &&
+        left.mappingApplied === right.mappingApplied &&
+        left.requestedScope === right.requestedScope &&
+        left.appliedScope === right.appliedScope &&
+        left.requestedSourcePriority === right.requestedSourcePriority &&
+        left.appliedSourcePriority === right.appliedSourcePriority &&
+        sameStringArray(left.resolutionNotes, right.resolutionNotes) &&
+        left.jarType === right.jarType &&
+        sameStringArray(left.mappingChain, right.mappingChain) &&
+        left.remapFailures === right.remapFailures &&
+        left.mappingAutoDetected === right.mappingAutoDetected &&
+        sameScopeFallback(left.scopeFallback, right.scopeFallback) &&
+        sameResolutionTrace(left.resolutionTrace, right.resolutionTrace));
+}
 const INDEX_SCHEMA_VERSION = 1;
 const SYMBOL_KINDS = ["class", "interface", "enum", "record", "method", "field"];
 function isSymbolKind(value) {
@@ -77,9 +172,37 @@ function hasExactVersionToken(path, version) {
         return false;
     }
     // Avoid prefix false-positives like "1.21.1" matching "1.21.10".
-    const pattern = new RegExp(`(^|[^0-9a-z])${escapeRegexLiteral(normalizedVersion)}([^0-9a-z]|$)`, "i");
+    const cached = VERSION_TOKEN_REGEX_CACHE.get(normalizedVersion);
+    const pattern = cached
+        ?? rememberCachedRegex(VERSION_TOKEN_REGEX_CACHE, normalizedVersion, 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 buildResolveArtifactParams(target, extra = {}) {
+    return {
+        target: {
+            kind: target.kind,
+            value: target.value
+        },
+        ...extra
+    };
+}
 function normalizeOptionalProjectPath(projectPath) {
     if (!projectPath) {
         return undefined;
@@ -91,19 +214,68 @@ function normalizeOptionalProjectPath(projectPath) {
     const normalized = normalizePathForHost(trimmed, undefined, "projectPath");
     return isAbsolute(normalized) ? normalized : resolvePath(process.cwd(), normalized);
 }
+function resolveGradleUserHomePath() {
+    const configured = process.env.GRADLE_USER_HOME?.trim();
+    if (!configured) {
+        return resolvePath(homedir(), ".gradle");
+    }
+    const normalized = normalizePathForHost(configured, undefined, "GRADLE_USER_HOME");
+    return isAbsolute(normalized) ? normalized : resolvePath(process.cwd(), normalized);
+}
 function buildVersionSourceSearchRoots(projectPath) {
     const roots = new Set();
     if (projectPath) {
         roots.add(resolvePath(projectPath, ".gradle", "loom-cache"));
         roots.add(resolvePath(projectPath, ".gradle-user", "caches", "fabric-loom"));
         roots.add(resolvePath(projectPath, ".gradle", "caches", "fabric-loom"));
-        return [...roots];
+        const projectParent = dirname(projectPath);
+        roots.add(resolvePath(projectParent, ".gradle-user-home", "loom-cache"));
+        roots.add(resolvePath(projectParent, ".gradle-user-home", "caches", "fabric-loom"));
     }
-    const homeGradle = resolvePath(homedir(), ".gradle");
+    const homeGradle = resolveGradleUserHomePath();
     roots.add(resolvePath(homeGradle, "loom-cache"));
     roots.add(resolvePath(homeGradle, "caches", "fabric-loom"));
     return [...roots];
 }
+function looksLikeMinecraftSourceArtifact(path, hasMinecraftNamespace) {
+    if (hasMinecraftNamespace) {
+        return true;
+    }
+    const normalizedPath = normalizePathStyle(path).toLowerCase();
+    return (normalizedPath.includes("/minecraftmaven/") ||
+        normalizedPath.includes("/net/minecraft/") ||
+        /(?:^|\/)minecraft(?:-[a-z0-9._+]+)*-sources\.jar$/i.test(normalizedPath) ||
+        normalizedPath.includes("minecraft-merged") ||
+        normalizedPath.includes("minecraft-common") ||
+        normalizedPath.includes("minecraft-clientonly") ||
+        normalizedPath.includes("minecraft-client") ||
+        normalizedPath.includes("minecraft-server"));
+}
+function normalizeRequestedArtifactScope(scope) {
+    return scope ?? "vanilla";
+}
+function inferAppliedArtifactScope(input) {
+    if (input.scopeFallback?.applied === "vanilla") {
+        return "vanilla";
+    }
+    if (input.requestedScope === "vanilla") {
+        return "vanilla";
+    }
+    const joinedPath = `${normalizePathStyle(input.jarPath)} ${normalizePathStyle(input.resolvedSourceJarPath ?? "")}`.toLowerCase();
+    if (joinedPath.includes("minecraft-merged")) {
+        return "merged";
+    }
+    if (input.requestedScope === "loader" && joinedPath.includes("merged")) {
+        return "merged";
+    }
+    return input.requestedScope;
+}
+function scopeToJarType(scope) {
+    if (scope === "vanilla") {
+        return "vanilla-client";
+    }
+    return scope;
+}
 function parseQualifiedMethodSymbol(symbol) {
     const trimmed = symbol.trim();
     const separator = trimmed.lastIndexOf(".");
@@ -166,11 +338,18 @@ const COMMON_SOURCE_ROOTS = [
     "quilt/src/main/java",
     "quilt/src/client/java"
 ];
+const MIXIN_PROJECT_DISCOVERY_IGNORES = [
+    "**/.git/**",
+    "**/.gradle/**",
+    "**/build/**",
+    "**/out/**",
+    "**/node_modules/**"
+];
 function normalizeMapping(mapping) {
     if (mapping == null) {
-        return "official";
+        return "obfuscated";
     }
-    if (mapping === "official" ||
+    if (mapping === "obfuscated" ||
         mapping === "mojang" ||
         mapping === "intermediary" ||
         mapping === "yarn") {
@@ -181,8 +360,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 +373,7 @@ function normalizeAccessWidenerNamespace(namespace) {
     if (normalized === "named") {
         return "yarn";
     }
-    if (normalized === "official" ||
+    if (normalized === "obfuscated" ||
         normalized === "mojang" ||
         normalized === "intermediary" ||
         normalized === "yarn") {
@@ -234,11 +413,11 @@ function sortDiffMemberChanges(changes) {
         if (keyCompare !== 0) {
             return keyCompare;
         }
-        const fromOwnerCompare = left.from.ownerFqn.localeCompare(right.from.ownerFqn);
+        const fromOwnerCompare = (left.from?.ownerFqn ?? "").localeCompare(right.from?.ownerFqn ?? "");
         if (fromOwnerCompare !== 0) {
             return fromOwnerCompare;
         }
-        return left.to.ownerFqn.localeCompare(right.to.ownerFqn);
+        return (left.to?.ownerFqn ?? "").localeCompare(right.to?.ownerFqn ?? "");
     });
 }
 function changedMemberFields(fromMember, toMember, includeDescriptor) {
@@ -311,6 +490,16 @@ function emptyDiffDelta() {
         modified: []
     };
 }
+function compactDiffDelta(delta) {
+    return {
+        added: delta.added,
+        removed: delta.removed,
+        modified: delta.modified.map((change) => ({
+            key: change.key,
+            changed: [...change.changed]
+        }))
+    };
+}
 function normalizeIntent(intent) {
     if (intent === "path" || intent === "text") {
         return intent;
@@ -333,10 +522,16 @@ 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) {
+    const cached = GLOB_REGEX_CACHE.get(pattern);
+    if (cached) {
+        GLOB_REGEX_CACHE.delete(pattern);
+        GLOB_REGEX_CACHE.set(pattern, cached);
+        return cached;
+    }
     const REGEX_META = /[-/\\^$+.()|[\]{}]/;
     let result = "";
     let i = 0;
@@ -363,7 +558,7 @@ function buildGlobRegex(pattern) {
             i += 1;
         }
     }
-    return new RegExp(`^${result}$`);
+    return rememberCachedRegex(GLOB_REGEX_CACHE, pattern, new RegExp(`^${result}$`));
 }
 function globToSqlLike(pattern) {
     let result = "";
@@ -412,14 +607,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 +614,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 +707,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) {
@@ -583,6 +734,11 @@ export class SourceService {
     versionDiffService;
     modDecompileService;
     modSearchService;
+    cacheMetricsState = {
+        entries: 0,
+        totalContentBytes: 0,
+        lru: []
+    };
     constructor(explicitConfig, metrics = new RuntimeMetrics()) {
         this.config = explicitConfig ?? loadConfig();
         this.metrics = metrics;
@@ -642,14 +798,18 @@ export class SourceService {
                     continue;
                 }
                 const hasMinecraftNamespace = javaEntries.some((entry) => normalizePathStyle(entry).startsWith("net/minecraft/"));
-                const score = (hasMinecraftNamespace ? 10_000 : 0) +
+                const looksLikeMinecraftArtifact = looksLikeMinecraftSourceArtifact(normalizedPath, hasMinecraftNamespace);
+                const exactVersionMatch = hasExactVersionToken(normalizedPath, input.version);
+                const score = (looksLikeMinecraftArtifact ? 20_000 : 0) +
+                    (hasMinecraftNamespace ? 10_000 : 0) +
                     (lower.includes("minecraft-merged") ? 2_000 : 0) +
-                    (lower.includes(input.version.toLowerCase()) ? 1_000 : 0) +
+                    (exactVersionMatch ? 1_000 : 0) +
                     Math.min(javaEntries.length, 500);
                 candidates.push({
                     jarPath: normalizedPath,
                     javaEntryCount: javaEntries.length,
                     hasMinecraftNamespace,
+                    looksLikeMinecraftArtifact,
                     score
                 });
             }
@@ -660,14 +820,16 @@ export class SourceService {
             }
             return left.jarPath.localeCompare(right.jarPath);
         });
-        const selected = candidates.find((candidate) => candidate.hasMinecraftNamespace) ?? candidates[0];
+        const selected = candidates.find((candidate) => candidate.looksLikeMinecraftArtifact && candidate.hasMinecraftNamespace) ??
+            candidates.find((candidate) => candidate.looksLikeMinecraftArtifact);
         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) {
@@ -677,6 +839,58 @@ export class SourceService {
             : "";
         return `${prefix}./gradlew genSources --no-daemon`;
     }
+    buildArtifactContentsSummary(input) {
+        const sourceKind = input.isDecompiled || input.origin === "decompiled" || !normalizeOptionalString(input.sourceJarPath)
+            ? "decompiled-binary"
+            : "source-jar";
+        const sourceCoverage = hasPartialNetMinecraftCoverage(input.qualityFlags) ? "partial" : "full";
+        return {
+            sourceKind,
+            indexedContentKinds: ["java-source"],
+            resourcesIncluded: false,
+            sourceCoverage
+        };
+    }
+    inferVersionFromContext(input) {
+        const direct = normalizeOptionalString(input.version);
+        if (direct) {
+            return direct;
+        }
+        const resolvedFromVersion = normalizeOptionalString(input.provenance?.resolvedFrom.version);
+        if (resolvedFromVersion) {
+            return resolvedFromVersion;
+        }
+        if (input.provenance?.target.kind === "version") {
+            const targetVersion = normalizeOptionalString(input.provenance.target.value);
+            if (targetVersion) {
+                return targetVersion;
+            }
+        }
+        const coordinate = normalizeOptionalString(input.coordinate);
+        if (coordinate) {
+            try {
+                return parseCoordinate(coordinate).version;
+            }
+            catch {
+                return undefined;
+            }
+        }
+        return undefined;
+    }
+    async resolveVersionContext(input) {
+        const inferredVersion = this.inferVersionFromContext(input);
+        if (inferredVersion) {
+            return inferredVersion;
+        }
+        if (!input.preferProjectVersion || !input.projectPath) {
+            return undefined;
+        }
+        const detected = await this.workspaceMappingService.detectProjectMinecraftVersion(input.projectPath);
+        if (detected) {
+            input.warnings.push(`Using project version "${detected}" from gradle.properties because the artifact metadata did not include a version.`);
+        }
+        return detected;
+    }
     async resolveArtifact(input) {
         const kind = input.target.kind;
         let value = input.target.value?.trim();
@@ -734,13 +948,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({
@@ -788,7 +1002,7 @@ export class SourceService {
                     if (isVanillaMojang && input.projectPath) {
                         suggestedCall = {
                             tool: "resolve-artifact",
-                            params: { targetKind: kind, targetValue: value, mapping: "mojang", scope: "merged", projectPath: input.projectPath }
+                            params: buildResolveArtifactParams({ kind, value }, { mapping: "mojang", scope: "merged", projectPath: input.projectPath })
                         };
                         nextAction =
                             "scope=vanilla blocks Loom cache discovery needed for mojang mapping. " +
@@ -797,24 +1011,25 @@ export class SourceService {
                     else if (isVanillaMojang) {
                         suggestedCall = {
                             tool: "resolve-artifact",
-                            params: { targetKind: kind, targetValue: value, mapping: "official", scope: "vanilla" }
+                            params: buildResolveArtifactParams({ kind, 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: buildResolveArtifactParams({ kind, 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,
                         message: caughtError.message,
                         details: {
                             ...(caughtError.details ?? {}),
+                            artifactOrigin: resolved.origin,
                             searchedPaths: versionSourceDiscovery?.searchedPaths ?? [],
                             candidateArtifacts: versionSourceDiscovery?.candidateArtifacts ?? resolved.adjacentSourceCandidates ?? [],
                             recommendedCommand: this.buildVersionSourceRecoveryCommand(input.projectPath),
@@ -834,14 +1049,17 @@ export class SourceService {
                         details: {
                             mapping: effectiveMapping,
                             target: { kind, value },
-                            nextAction: "Use targetKind=version or a versioned Maven coordinate so mapping artifacts can be resolved.",
-                            suggestedCall: { tool: "resolve-artifact", params: { targetKind: "version", targetValue: value, ...(scope ? { scope } : {}) } }
+                            nextAction: "Use target: { kind: \"version\", value } or a versioned Maven coordinate so mapping artifacts can be resolved.",
+                            suggestedCall: {
+                                tool: "resolve-artifact",
+                                params: buildResolveArtifactParams({ kind: "version", value }, { ...(scope ? { scope } : {}) })
+                            }
                         }
                     });
                 }
                 const mappingAvailability = await this.mappingService.ensureMappingAvailable({
                     version: resolved.version,
-                    sourceMapping: "official",
+                    sourceMapping: "obfuscated",
                     targetMapping: effectiveMapping,
                     sourcePriority: input.sourcePriority
                 });
@@ -864,6 +1082,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({
@@ -874,7 +1096,10 @@ export class SourceService {
                                 selectedSourceJar: versionSourceDiscovery.selectedSourceJarPath,
                                 candidateArtifacts: versionSourceDiscovery.candidateArtifacts,
                                 nextAction: "Use strictVersion=false (default) to allow approximation, or ensure the exact version source jar is in the Loom cache.",
-                                suggestedCall: { tool: "resolve-artifact", params: { targetKind: "version", targetValue: value, strictVersion: false } }
+                                suggestedCall: {
+                                    tool: "resolve-artifact",
+                                    params: buildResolveArtifactParams({ kind: "version", value }, { strictVersion: false })
+                                }
                             }
                         });
                     }
@@ -882,7 +1107,7 @@ export class SourceService {
                     warnings.push(`Requested version "${value}" but resolved source jar does not contain exact version string: ${versionSourceDiscovery.selectedSourceJarPath}`);
                 }
             }
-            resolved.qualityFlags = [...new Set(resolved.qualityFlags)];
+            resolved.qualityFlags = dedupeQualityFlags(resolved.qualityFlags);
             await this.ingestIfNeeded(resolved);
             let sampleEntries;
             if (resolved.sourceJarPath) {
@@ -912,6 +1137,12 @@ export class SourceService {
                 provenance,
                 qualityFlags: resolved.qualityFlags,
                 repoUrl: resolved.repoUrl,
+                artifactContents: this.buildArtifactContentsSummary({
+                    origin: resolved.origin,
+                    sourceJarPath: resolved.sourceJarPath,
+                    isDecompiled: resolved.isDecompiled,
+                    qualityFlags: resolved.qualityFlags
+                }),
                 warnings,
                 sampleEntries
             };
@@ -942,8 +1173,14 @@ export class SourceService {
             if (!query) {
                 return {
                     hits: [],
-                    totalApprox: 0,
-                    mappingApplied: artifact.mappingApplied ?? "official"
+                    mappingApplied: artifact.mappingApplied ?? "obfuscated",
+                    returnedNamespace: artifact.mappingApplied ?? "obfuscated",
+                    artifactContents: this.buildArtifactContentsSummary({
+                        origin: artifact.origin,
+                        sourceJarPath: artifact.sourceJarPath,
+                        isDecompiled: artifact.isDecompiled,
+                        qualityFlags: artifact.qualityFlags
+                    })
                 };
             }
             const intent = normalizeIntent(input.intent);
@@ -961,12 +1198,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 +1214,7 @@ export class SourceService {
                 intent,
                 match,
                 queryMode,
-                scope,
-                includeDefinition
+                scope
             });
             const decodedCursor = decodeSearchCursor(input.cursor);
             const cursor = decodedCursor?.contextKey === cursorContext ? decodedCursor : undefined;
@@ -991,52 +1230,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 +1274,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 +1286,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 +1300,18 @@ 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",
+                returnedNamespace: artifact.mappingApplied ?? "obfuscated",
+                artifactContents: this.buildArtifactContentsSummary({
+                    origin: artifact.origin,
+                    sourceJarPath: artifact.sourceJarPath,
+                    isDecompiled: artifact.isDecompiled,
+                    qualityFlags: artifact.qualityFlags
+                })
             };
         }
         finally {
@@ -1139,7 +1348,14 @@ export class SourceService {
                 content,
                 contentBytes: fullBytes,
                 truncated,
-                mappingApplied: artifact.mappingApplied ?? "official"
+                mappingApplied: artifact.mappingApplied ?? "obfuscated",
+                returnedNamespace: artifact.mappingApplied ?? "obfuscated",
+                artifactContents: this.buildArtifactContentsSummary({
+                    origin: artifact.origin,
+                    sourceJarPath: artifact.sourceJarPath,
+                    isDecompiled: artifact.isDecompiled,
+                    qualityFlags: artifact.qualityFlags
+                })
             };
         }
         finally {
@@ -1151,15 +1367,29 @@ export class SourceService {
         try {
             const artifact = this.getArtifact(input.artifactId);
             const limit = clampLimit(input.limit, 200, 2000);
+            const warnings = [];
             const page = this.filesRepo.listFiles(artifact.artifactId, {
                 limit,
                 cursor: input.cursor,
                 prefix: input.prefix
             });
+            const normalizedPrefix = normalizeOptionalString(input.prefix);
+            if (normalizedPrefix &&
+                page.items.length === 0 &&
+                (normalizedPrefix.startsWith("assets/") || normalizedPrefix.startsWith("data/"))) {
+                warnings.push("Indexed artifacts currently include Java source only; non-Java resources are not indexed. Inspect the original jar on disk if you need assets or data files.");
+            }
             return {
                 items: page.items,
                 nextCursor: page.nextCursor,
-                mappingApplied: artifact.mappingApplied ?? "official"
+                mappingApplied: artifact.mappingApplied ?? "obfuscated",
+                artifactContents: this.buildArtifactContentsSummary({
+                    origin: artifact.origin,
+                    sourceJarPath: artifact.sourceJarPath,
+                    isDecompiled: artifact.isDecompiled,
+                    qualityFlags: artifact.qualityFlags
+                }),
+                warnings
             };
         }
         finally {
@@ -1298,21 +1528,24 @@ export class SourceService {
                 resolved: false,
                 status: "mapping_unavailable",
                 candidates: [],
+                candidateCount: 0,
                 workspaceDetection,
                 warnings
             };
         }
         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
+                sourcePriority: input.sourcePriority,
+                maxCandidates: input.maxCandidates
             });
             return {
                 ...exact,
@@ -1342,6 +1575,7 @@ export class SourceService {
                     resolved: false,
                     status: "not_found",
                     candidates: [],
+                    candidateCount: 0,
                     workspaceDetection,
                     warnings: [...warnings, ...matrix.warnings]
                 };
@@ -1369,6 +1603,7 @@ export class SourceService {
                 status: "resolved",
                 resolvedSymbol,
                 candidates: [resolvedCandidate],
+                candidateCount: 1,
                 workspaceDetection,
                 warnings: [...warnings, ...matrix.warnings]
             };
@@ -1381,7 +1616,8 @@ export class SourceService {
             descriptor,
             sourceMapping: input.sourceMapping,
             targetMapping: mappingApplied,
-            sourcePriority: input.sourcePriority
+            sourcePriority: input.sourcePriority,
+            maxCandidates: input.maxCandidates
         });
         const filtered = mapped.candidates.filter((candidate) => candidate.kind === kind);
         let status;
@@ -1404,6 +1640,8 @@ export class SourceService {
             status,
             resolvedSymbol: status === "resolved" ? filtered[0] : undefined,
             candidates: filtered,
+            candidateCount: mapped.candidateCount,
+            candidatesTruncated: mapped.candidatesTruncated,
             workspaceDetection,
             warnings: [...warnings, ...mapped.warnings]
         };
@@ -1473,14 +1711,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);
                 }
@@ -1574,6 +1812,7 @@ export class SourceService {
         const className = input.className.trim();
         const fromVersion = input.fromVersion.trim();
         const toVersion = input.toVersion.trim();
+        const includeFullDiff = input.includeFullDiff ?? true;
         if (!className || !fromVersion || !toVersion) {
             throw createError({
                 code: ERROR_CODES.INVALID_INPUT,
@@ -1630,18 +1869,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 +1901,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,18 +1979,46 @@ 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) => {
+                if (!change.from || !change.to) {
+                    throw createError({
+                        code: ERROR_CODES.INTERNAL,
+                        message: "Modified diff members are missing before remap.",
+                        details: {
+                            key: change.key,
+                            kind,
+                            fromVersion,
+                            toVersion,
+                            mapping
+                        }
+                    });
+                }
                 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] };
+                const fromMember = fromResult.members[0];
+                const toMember = toResult.members[0];
+                if (!fromMember || !toMember) {
+                    throw createError({
+                        code: ERROR_CODES.INTERNAL,
+                        message: "Failed to remap modified diff members.",
+                        details: {
+                            key: change.key,
+                            kind,
+                            fromVersion,
+                            toVersion,
+                            mapping
+                        }
+                    });
+                }
+                return { ...change, from: fromMember, to: toMember };
             }));
             return { added: addedResult.members, removed: removedResult.members, modified: remappedModified };
         };
@@ -1794,9 +2061,9 @@ export class SourceService {
                 toVersion
             },
             classChange,
-            constructors: remappedConstructors,
-            methods: remappedMethods,
-            fields: remappedFields,
+            constructors: includeFullDiff ? remappedConstructors : compactDiffDelta(remappedConstructors),
+            methods: includeFullDiff ? remappedMethods : compactDiffDelta(remappedMethods),
+            fields: includeFullDiff ? remappedFields : compactDiffDelta(remappedFields),
             summary,
             warnings
         };
@@ -1817,7 +2084,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 +2114,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 +2148,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();
@@ -1905,7 +2192,7 @@ export class SourceService {
         if (normalizedArtifactId && input.target) {
             throw createError({
                 code: ERROR_CODES.INVALID_INPUT,
-                message: "artifactId and targetKind/targetValue are mutually exclusive.",
+                message: "artifactId and target are mutually exclusive.",
                 details: {
                     artifactId: normalizedArtifactId,
                     target: input.target
@@ -1919,6 +2206,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 +2234,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 +2246,130 @@ 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;
         }
-        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.`;
+        version = await this.resolveVersionContext({
+            version,
+            provenance,
+            coordinate,
+            projectPath: input.projectPath,
+            preferProjectVersion: input.preferProjectVersion,
+            warnings
+        });
+        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;
             }
-            else if (targetKind === "version" && scope && scope !== "merged" && input.projectPath) {
-                nextAction +=
-                    ` The class may exist in merged sources; retry with scope: "merged".`;
+            attemptedBinaryFallback = true;
+            const normalizedBinaryJarPath = normalizeOptionalString(binaryJarPath);
+            if (!normalizedBinaryJarPath) {
+                return false;
             }
-            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 } }
-                }
+            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 = dedupeQualityFlags([...(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);
+        }
+        if (!filePath) {
+            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
+            });
+        }
+        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);
         }
-        const row = this.filesRepo.getFileContent(artifactId, filePath);
         if (!row) {
-            const simpleName = className.split(/[.$]/).at(-1) ?? className;
-            throw createError({
-                code: ERROR_CODES.CLASS_NOT_FOUND,
-                message: `Source for class "${className}" was not found.`,
-                details: {
-                    artifactId,
-                    className,
-                    filePath,
-                    ...(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 +2420,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 +2438,19 @@ export class SourceService {
             },
             truncated,
             ...(charsTruncated ? { charsTruncated } : {}),
-            origin,
-            artifactId,
+            origin: activeOrigin,
+            artifactId: activeArtifactId,
             requestedMapping,
-            mappingApplied,
+            mappingApplied: activeMappingApplied,
+            returnedNamespace: activeMappingApplied,
             provenance: normalizedProvenance,
-            qualityFlags,
+            qualityFlags: activeQualityFlags,
+            artifactContents: this.buildArtifactContentsSummary({
+                origin: activeOrigin,
+                sourceJarPath: activeSourceJarPath,
+                isDecompiled: activeOrigin === "decompiled",
+                qualityFlags: activeQualityFlags
+            }),
             ...(resolvedOutputFile ? { outputFile: resolvedOutputFile } : {}),
             warnings
         };
@@ -2095,7 +2474,7 @@ export class SourceService {
         if (normalizedArtifactId && input.target) {
             throw createError({
                 code: ERROR_CODES.INVALID_INPUT,
-                message: "artifactId and targetKind/targetValue are mutually exclusive.",
+                message: "artifactId and target are mutually exclusive.",
                 details: {
                     artifactId: normalizedArtifactId,
                     target: input.target
@@ -2109,6 +2488,8 @@ export class SourceService {
         let provenance;
         let qualityFlags = [];
         let binaryJarPath;
+        let sourceJarPath;
+        let coordinate;
         if (parsedMaxMembers != null && parsedMaxMembers > 5000) {
             warnings.push(`maxMembers was clamped to 5000 from ${parsedMaxMembers}.`);
         }
@@ -2137,7 +2518,9 @@ export class SourceService {
             provenance = resolved.provenance;
             qualityFlags = [...resolved.qualityFlags];
             binaryJarPath = resolved.binaryJarPath;
+            sourceJarPath = resolved.resolvedSourceJarPath;
             version = resolved.version;
+            coordinate = resolved.coordinate;
         }
         else {
             const artifact = this.getArtifact(artifactId);
@@ -2146,16 +2529,29 @@ export class SourceService {
             provenance = artifact.provenance;
             qualityFlags = artifact.qualityFlags;
             binaryJarPath = artifact.binaryJarPath;
+            sourceJarPath = artifact.sourceJarPath;
             version = artifact.version;
+            coordinate = artifact.coordinate;
         }
-        if (requestedMapping !== "official" && !version) {
+        version = await this.resolveVersionContext({
+            version,
+            provenance,
+            coordinate,
+            projectPath: input.projectPath,
+            preferProjectVersion: input.preferProjectVersion,
+            warnings
+        });
+        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.",
-                    suggestedCall: { tool: "resolve-artifact", params: { targetKind: "version", targetValue: "latest" } }
+                    nextAction: "Resolve with target: { kind: \"version\", value: ... } or specify a versioned coordinate.",
+                    suggestedCall: {
+                        tool: "resolve-artifact",
+                        params: buildResolveArtifactParams({ kind: "version", value: "latest" })
+                    }
                 }
             });
         }
@@ -2166,33 +2562,39 @@ export class SourceService {
                 details: {
                     artifactId,
                     className,
-                    nextAction: "Resolve with targetKind=jar or targetKind=version, or use an artifact that has a binary jar."
+                    nextAction: "Resolve with target: { kind: \"jar\" | \"version\", value: ... } or use an artifact that has a binary jar."
                 }
             });
         }
-        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));
@@ -2242,98 +2644,169 @@ export class SourceService {
             artifactId,
             requestedMapping,
             mappingApplied,
+            returnedNamespace: requestedMapping,
             provenance: normalizedProvenance,
             qualityFlags,
+            artifactContents: this.buildArtifactContentsSummary({
+                origin,
+                sourceJarPath,
+                isDecompiled: origin === "decompiled",
+                qualityFlags
+            }),
             warnings
         };
     }
     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];
+        const { input: sourceInput, ...sharedInput } = input;
+        const mode = sourceInput.mode;
+        if (mode === "inline") {
+            const singleResult = await this.validateMixinSingle({
+                ...sharedInput,
+                source: sourceInput.source
+            });
+            return this.applyValidateMixinOutputCompaction(this.buildValidateMixinOutput(mode, [
+                {
+                    source: {
+                        kind: "inline",
+                        label: "<inline>"
+                    },
+                    result: singleResult
                 }
-                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"];
-                    }
+            ]), input);
+        }
+        if (mode === "path") {
+            const resolvedPath = this.resolveMixinInputPath(sourceInput.path, "path");
+            const singleResult = await this.validateMixinSingle({
+                ...sharedInput,
+                sourcePath: sourceInput.path
+            });
+            return this.applyValidateMixinOutputCompaction(this.buildValidateMixinOutput(mode, [
+                {
+                    source: {
+                        kind: "path",
+                        label: resolvedPath,
+                        path: resolvedPath
+                    },
+                    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));
-                    }
+            ]), 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 resolvedInput = mode === "project"
+            ? this.createProjectValidateMixinConfigInput(input)
+            : input;
+        const configSources = await this.resolveMixinConfigSources(resolvedInput);
+        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
+        })), resolvedInput);
+    }
+    createProjectValidateMixinConfigInput(input) {
+        if (input.input.mode !== "project") {
+            return input;
+        }
+        const resolvedProjectPath = this.resolveMixinInputPath(input.input.path, "path");
+        const configPaths = fastGlob.sync(["**/*.mixins.json"], {
+            cwd: resolvedProjectPath,
+            absolute: true,
+            onlyFiles: true,
+            ignore: [...MIXIN_PROJECT_DISCOVERY_IGNORES]
+        }).sort((left, right) => left.localeCompare(right));
+        if (configPaths.length === 0) {
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: `No mixin config JSON files were found under project path "${input.input.path}".`,
+                details: {
+                    nextAction: "Use input.mode='config' with explicit configPaths[], or point input.path at the workspace root that contains *.mixins.json files."
                 }
+            });
+        }
+        return {
+            ...input,
+            projectPath: input.projectPath ?? resolvedProjectPath,
+            input: {
+                mode: "config",
+                configPaths
             }
-            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 });
+        };
+    }
+    shouldRetryValidateMixinWithMavenFirst(input, result) {
+        const initialPriority = input.retryState?.initialSourcePriority ?? input.sourcePriority ?? this.config.mappingSourcePriority;
+        if (input.retryState?.attempted || initialPriority !== "loom-first") {
+            return false;
+        }
+        if (result.validationStatus !== "partial") {
+            return false;
         }
-        // Batch mode: delegate to validateMixinBatch when sourcePaths is provided
-        if (input.sourcePaths && input.sourcePaths.length > 0) {
-            return this.validateMixinBatch(input);
+        if (result.summary.membersSkipped > 0) {
+            return true;
         }
+        return result.issues.some((issue) => issue.resolutionPath === "source-signature-unavailable" ||
+            issue.resolutionPath === "target-mapping-failed" ||
+            issue.resolutionPath === "member-remap-failed");
+    }
+    findValidateMixinClassMapping(input) {
+        const cache = input.batchCaches?.classMappings;
+        if (!cache) {
+            return this.mappingService.findMapping({
+                version: input.version,
+                kind: "class",
+                name: input.className,
+                sourceMapping: input.sourceMapping,
+                targetMapping: input.targetMapping,
+                sourcePriority: input.sourcePriority
+            });
+        }
+        const cacheKey = [
+            input.version,
+            input.className,
+            input.sourceMapping,
+            input.targetMapping,
+            input.sourcePriority
+        ].join("\0");
+        const cached = cache.get(cacheKey);
+        if (cached) {
+            return cached;
+        }
+        const pending = this.mappingService.findMapping({
+            version: input.version,
+            kind: "class",
+            name: input.className,
+            sourceMapping: input.sourceMapping,
+            targetMapping: input.targetMapping,
+            sourcePriority: input.sourcePriority
+        }).catch((error) => {
+            cache.delete(cacheKey);
+            throw error;
+        });
+        cache.set(cacheKey, pending);
+        return pending;
+    }
+    async validateMixinSingle(input) {
         let version = input.version.trim();
+        const requestedScope = normalizeRequestedArtifactScope(input.scope);
+        const currentSourcePriority = input.sourcePriority ?? this.config.mappingSourcePriority;
+        const initialSourcePriority = input.retryState?.initialSourcePriority ?? currentSourcePriority;
         if (!version) {
             throw createError({ code: ERROR_CODES.INVALID_INPUT, message: "version must be non-empty." });
         }
@@ -2394,22 +2867,25 @@ export class SourceService {
         }
         // Resolve jar: use Loom cache for non-vanilla scope with projectPath
         let jarPath;
+        let resolvedArtifact;
+        let signatureLookupMapping = "obfuscated";
         let scopeFallback;
         if (input.scope && input.scope !== "vanilla" && input.projectPath) {
             try {
-                const resolved = await this.resolveArtifact({
+                resolvedArtifact = await this.resolveArtifact({
                     target: { kind: "version", value: version },
                     mapping: requestedMapping,
-                    sourcePriority: input.sourcePriority,
+                    sourcePriority: currentSourcePriority,
                     projectPath: input.projectPath,
                     scope: input.scope,
                     preferProjectVersion: false
                 });
-                jarPath = resolved.binaryJarPath ?? (await this.versionService.resolveVersionJar(version)).jarPath;
-                warnings.push(...resolved.warnings);
-                mappingApplied = resolved.mappingApplied;
-                if (resolved.version) {
-                    version = resolved.version;
+                jarPath = resolvedArtifact.binaryJarPath ?? (await this.versionService.resolveVersionJar(version)).jarPath;
+                warnings.push(...resolvedArtifact.warnings);
+                mappingApplied = resolvedArtifact.mappingApplied;
+                signatureLookupMapping = resolvedArtifact.mappingApplied;
+                if (resolvedArtifact.version) {
+                    version = resolvedArtifact.version;
                 }
             }
             catch (scopeErr) {
@@ -2430,6 +2906,7 @@ export class SourceService {
         if (jarPath.includes("-sources.jar")) {
             warnings.push(`Resolved jar appears to be a sources jar. Falling back to vanilla client jar.`);
             jarPath = (await this.versionService.resolveVersionJar(version)).jarPath;
+            signatureLookupMapping = "obfuscated";
             scopeFallback = {
                 requested: input.scope ?? "vanilla",
                 applied: "vanilla",
@@ -2442,7 +2919,7 @@ export class SourceService {
             const health = await this.mappingService.checkMappingHealth({
                 version,
                 requestedMapping,
-                sourcePriority: input.sourcePriority
+                sourcePriority: currentSourcePriority
             });
             const jarAvailable = existsSync(jarPath);
             healthReport = {
@@ -2489,51 +2966,51 @@ export class SourceService {
                     }
                 }
             }
-            let officialName = resolvedClassName;
-            if (requestedMapping !== "official") {
+            let obfuscatedName = resolvedClassName;
+            if (requestedMapping !== signatureLookupMapping) {
                 try {
-                    const mapped = await this.mappingService.findMapping({
+                    const mapped = await this.findValidateMixinClassMapping({
                         version,
-                        kind: "class",
-                        name: resolvedClassName,
+                        className: resolvedClassName,
                         sourceMapping: requestedMapping,
-                        targetMapping: "official",
-                        sourcePriority: input.sourcePriority
+                        targetMapping: signatureLookupMapping,
+                        sourcePriority: currentSourcePriority,
+                        batchCaches: input.batchCaches
                     });
                     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 ${signatureLookupMapping}; 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}" while preparing ${signatureLookupMapping} lookup; 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 !== signatureLookupMapping) {
                     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, signatureLookupMapping, requestedMapping, currentSourcePriority, warnings),
+                            this.remapSignatureMembers(sig.methods, "method", version, signatureLookupMapping, requestedMapping, currentSourcePriority, warnings),
+                            this.remapSignatureMembers(sig.fields, "field", version, signatureLookupMapping, requestedMapping, currentSourcePriority, warnings)
                         ]);
                         constructors = ctorResult.members;
                         methods = methodResult.members;
@@ -2555,9 +3032,17 @@ 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 ${signatureLookupMapping} names. ` +
+                            `Member names shown may be in the ${signatureLookupMapping} runtime namespace.`);
+                        mappingApplied = signatureLookupMapping;
+                        resolutionTrace?.push({
+                            target: target.className,
+                            step: "remap",
+                            input: resolvedClassName,
+                            output: `${signatureLookupMapping} fallback`,
+                            success: false,
+                            detail: remapErr instanceof Error ? remapErr.message : String(remapErr)
+                        });
                     }
                 }
                 targetMembers.set(target.className, {
@@ -2568,17 +3053,15 @@ export class SourceService {
                 });
             }
             catch (sigErr) {
-                warnings.push(`Could not load signature for class "${resolvedClassName}" (official: "${officialName}").`);
-                signatureFailedTargets.add(target.className);
-                resolutionTrace?.push({ target: target.className, step: "signature", input: officialName, output: "CLASS_NOT_FOUND", success: false, detail: sigErr instanceof Error ? sigErr.message : String(sigErr) });
+                warnings.push(`Could not load signature for class "${resolvedClassName}" (obfuscated: "${obfuscatedName}").`);
+                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({
                         version, kind: "class", name: resolvedClassName,
-                        sourceMapping: requestedMapping, nameMode: "auto"
+                        sourceMapping: requestedMapping, nameMode: "auto", sourcePriority: currentSourcePriority
                     });
                     if (existenceCheck.resolved) {
-                        signatureFailedTargets.delete(target.className);
                         symbolExistsButSignatureFailed.add(target.className);
                         resolutionTrace?.push({ target: target.className, step: "fallback-check", input: resolvedClassName, output: "exists in mapping graph", success: true });
                     }
@@ -2587,23 +3070,35 @@ export class SourceService {
                     }
                 }
                 catch {
-                    // Fallback check failed — keep as signatureFailedTarget
+                    // Fallback check failed — treat as tool-limited partial validation.
+                    signatureFailedTargets.add(target.className);
                     resolutionTrace?.push({ target: target.className, step: "fallback-check", input: resolvedClassName, output: "check failed", success: false });
                 }
             }
         }
         // Fix toolHealth accuracy: reflect actual failures after target resolution
         if (healthReport) {
-            const hasFailures = signatureFailedTargets.size > 0 || mappingFailedTargets.size > 0;
+            const hasFailures = signatureFailedTargets.size > 0 ||
+                mappingFailedTargets.size > 0 ||
+                symbolExistsButSignatureFailed.size > 0;
             if (hasFailures && healthReport.overallHealthy) {
                 healthReport.overallHealthy = false;
-                healthReport.degradations.push(`${mappingFailedTargets.size} mapping failure(s), ${signatureFailedTargets.size} signature failure(s).`);
+                healthReport.degradations.push(`${mappingFailedTargets.size} mapping failure(s), ${signatureFailedTargets.size} signature failure(s), ${symbolExistsButSignatureFailed.size} partial validation target(s).`);
             }
         }
         const resolutionNotes = [];
         if (requestedMapping !== mappingApplied) {
             resolutionNotes.push(`Mapping fallback: requested "${requestedMapping}" but applied "${mappingApplied}" due to remapping failure.`);
         }
+        const appliedScope = inferAppliedArtifactScope({
+            requestedScope,
+            scopeFallback,
+            jarPath,
+            resolvedSourceJarPath: resolvedArtifact?.resolvedSourceJarPath
+        });
+        if (!scopeFallback && requestedScope !== appliedScope) {
+            resolutionNotes.push(`Scope adjusted during validation: requested "${requestedScope}" but resolved artifact looks like "${appliedScope}".`);
+        }
         // Count remap failures from warnings
         const REMAP_WARNING_RE = /^(?:Could not remap|Remap failed for)\b/;
         const remapFailures = warnings.filter((w) => REMAP_WARNING_RE.test(w)).length;
@@ -2617,26 +3112,30 @@ export class SourceService {
         }
         // Build mapping chain description
         const mappingChain = [];
-        if (requestedMapping !== "official") {
-            mappingChain.push(`${requestedMapping} → official`);
-            if (mappingApplied !== requestedMapping) {
-                mappingChain.push(`fallback to ${mappingApplied}`);
-            }
+        if (requestedMapping !== signatureLookupMapping) {
+            mappingChain.push(`${requestedMapping} → ${signatureLookupMapping}`);
+        }
+        if (mappingApplied !== signatureLookupMapping) {
+            mappingChain.push(`fallback to ${mappingApplied}`);
         }
         const provenance = {
             version,
             jarPath,
             requestedMapping,
             mappingApplied,
+            requestedScope,
+            appliedScope,
+            requestedSourcePriority: initialSourcePriority,
+            appliedSourcePriority: currentSourcePriority,
             resolutionNotes: resolutionNotes.length > 0 ? resolutionNotes : undefined,
-            jarType: scopeFallback ? "vanilla-client" : (input.scope && input.scope !== "vanilla" && input.projectPath) ? "merged" : "vanilla-client",
+            jarType: scopeToJarType(appliedScope),
             mappingChain: mappingChain.length > 0 ? mappingChain : undefined,
             remapFailures: remapFailures > 0 ? remapFailures : undefined,
             mappingAutoDetected: mappingAutoDetected || undefined,
             scopeFallback,
             resolutionTrace: resolutionTrace && resolutionTrace.length > 0 ? resolutionTrace : undefined
         };
-        const result = validateParsedMixin(parsed, targetMembers, warnings, provenance, confidence, mappingFailedTargets, input.explain, remapFailedMembers, signatureFailedTargets, input.explain ? { scope: input.scope, sourcePriority: input.sourcePriority, projectPath: input.projectPath, mapping: requestedMapping } : undefined, input.warningMode, healthReport, symbolExistsButSignatureFailed.size > 0 ? symbolExistsButSignatureFailed : undefined);
+        const result = refreshMixinValidationOutcome(validateParsedMixin(parsed, targetMembers, warnings, provenance, confidence, mappingFailedTargets, input.explain, remapFailedMembers, signatureFailedTargets, input.explain ? { scope: requestedScope, sourcePriority: currentSourcePriority, projectPath: input.projectPath, mapping: requestedMapping } : undefined, input.warningMode, healthReport, symbolExistsButSignatureFailed.size > 0 ? symbolExistsButSignatureFailed : undefined));
         // Apply minSeverity / hideUncertain filters
         const minSeverity = input.minSeverity ?? "all";
         const hideUncertain = input.hideUncertain ?? false;
@@ -2669,7 +3168,6 @@ export class SourceService {
                 parseWarnings: filteredParseWarnings
             };
             result.unfilteredSummary = unfilteredSummary;
-            result.valid = filteredDefiniteErrors === 0;
         }
         // Apply warningCategoryFilter
         if (input.warningCategoryFilter && input.warningCategoryFilter.length > 0) {
@@ -2693,7 +3191,6 @@ export class SourceService {
                 resolutionErrors: result.issues.filter((i) => i.resolutionPath != null).length,
                 parseWarnings: result.issues.filter((i) => i.category === "parse").length
             };
-            result.valid = catDefiniteErrors === 0;
         }
         // Apply treatInfoAsWarning filter
         if (input.treatInfoAsWarning === false && result.structuredWarnings) {
@@ -2707,51 +3204,217 @@ export class SourceService {
             result.structuredWarnings = undefined;
             result.aggregatedWarnings = undefined;
             result.toolHealth = undefined;
+            result.confidenceBreakdown = undefined;
             if (result.provenance) {
                 result.provenance.resolutionTrace = undefined;
             }
         }
+        refreshMixinValidationOutcome(result);
+        if (this.shouldRetryValidateMixinWithMavenFirst(input, result)) {
+            const retryWarning = `Retrying validate-mixin with sourcePriority="maven-first" after partial validation using "${currentSourcePriority}".`;
+            try {
+                const retried = await this.validateMixinSingle({
+                    ...input,
+                    source,
+                    sourcePath: undefined,
+                    sourcePriority: "maven-first",
+                    retryState: {
+                        attempted: true,
+                        initialSourcePriority
+                    }
+                });
+                retried.warnings = [retryWarning, ...retried.warnings];
+                if (retried.provenance) {
+                    retried.provenance.requestedSourcePriority = initialSourcePriority;
+                    retried.provenance.appliedSourcePriority = "maven-first";
+                    retried.provenance.resolutionNotes = [
+                        ...(retried.provenance.resolutionNotes ?? []),
+                        `Validation retried with sourcePriority "maven-first" after partial result from "${currentSourcePriority}".`
+                    ];
+                }
+                return refreshMixinValidationOutcome(retried);
+            }
+            catch (retryErr) {
+                result.warnings.unshift(`${retryWarning} Retry failed: ${retryErr instanceof Error ? retryErr.message : String(retryErr)}`);
+                return result;
+            }
+        }
         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 = [];
-        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) {
+        for (const rawConfigPath of input.input.configPaths) {
+            const resolvedConfigPath = this.resolveMixinInputPath(rawConfigPath, "configPath");
+            let configJson;
             try {
-                const singleResult = await this.validateMixin({
-                    ...input,
-                    sourcePaths: undefined,
-                    source: undefined,
-                    sourcePath: sp,
-                    warningMode: batchWarningMode
+                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)}`
                 });
-                results.push({ sourcePath: sp, result: singleResult });
-                if (singleResult.valid) {
-                    validCount++;
-                }
-                else {
-                    invalidCount++;
+            }
+            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 = [];
+        const batchWarningMode = input.warningMode ?? "aggregated";
+        const { input: _discardedInput, ...sharedInput } = input;
+        const batchCaches = {
+            classMappings: new Map()
+        };
+        for (const entry of entries) {
+            try {
+                const singleResult = await this.validateMixinSingle({
+                    ...sharedInput,
+                    sourcePath: entry.sourcePath,
+                    warningMode: batchWarningMode,
+                    batchCaches
+                });
+                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.applyValidateMixinOutputCompaction(this.buildValidateMixinOutput(mode, results), input);
+    }
+    applyValidateMixinOutputCompaction(output, input) {
+        let nextOutput = output;
+        const canHoistProvenance = nextOutput.provenance != null;
+        const warningCandidates = nextOutput.results
+            .map((entry) => entry.result?.warnings)
+            .filter((entry) => entry != null);
+        const canHoistWarnings = warningCandidates.length === 0
+            ? true
+            : warningCandidates.every((entry) => sameStringArray(entry, warningCandidates[0]));
+        if (input.reportMode === "summary-first") {
+            nextOutput = {
+                ...nextOutput,
+                results: nextOutput.results.map((entry) => (entry.result
+                    ? {
+                        ...entry,
+                        result: {
+                            ...entry.result,
+                            warnings: canHoistWarnings ? [] : entry.result.warnings,
+                            structuredWarnings: undefined,
+                            aggregatedWarnings: undefined,
+                            resolvedMembers: undefined,
+                            toolHealth: undefined,
+                            confidenceBreakdown: undefined,
+                            provenance: canHoistProvenance ? undefined : entry.result.provenance
+                        }
+                    }
+                    : entry))
+            };
+        }
+        if (input.includeIssues !== false) {
+            return nextOutput;
+        }
+        return {
+            ...nextOutput,
+            results: nextOutput.results.map((entry) => (entry.result
+                ? {
+                    ...entry,
+                    result: {
+                        ...entry.result,
+                        issues: []
+                    }
+                }
+                : entry))
+        };
+    }
+    buildValidateMixinOutput(mode, results) {
+        let valid = 0;
+        let partial = 0;
+        let invalid = 0;
+        let processingErrors = 0;
+        let totalValidationErrors = 0;
+        let totalValidationWarnings = 0;
+        const warningSet = new Set();
+        const incompleteReasonSet = 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++;
+            }
+            if (entry.result.validationStatus === "partial") {
+                partial++;
+            }
+            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) {
+                if (issue.kind === "validation-incomplete") {
+                    incompleteReasonSet.add(`validation-incomplete: ${issue.message}`);
+                }
                 const key = `${issue.kind}\0${issue.confidence ?? "unknown"}\0${issue.category ?? "validation"}`;
                 const existing = issueGroupMap.get(key);
                 if (existing) {
@@ -2771,39 +3434,37 @@ 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 provenanceCandidates = results
+            .map((entry) => entry.result?.provenance)
+            .filter((entry) => entry != null);
+        const provenance = provenanceCandidates.length === 0
+            ? undefined
+            : provenanceCandidates.every((entry) => sameMixinValidationProvenance(entry, provenanceCandidates[0]))
+                ? provenanceCandidates[0]
+                : 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,
+                partial,
+                invalid,
+                processingErrors,
                 totalValidationErrors,
-                totalValidationWarnings,
-                confidenceScore: batchConfidenceScore
+                totalValidationWarnings
             },
             issueSummary,
-            toolHealth: sharedHealth
+            provenance,
+            incompleteReasons: incompleteReasonSet.size > 0 ? [...incompleteReasonSet] : undefined,
+            toolHealth,
+            confidenceScore: confidenceScores.length > 0 ? Math.min(...confidenceScores) : undefined,
+            warnings: [...warningSet]
         };
     }
     async validateAccessWidener(input) {
@@ -2828,7 +3489,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 +3498,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 +3506,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 +3522,7 @@ export class SourceService {
             }
             try {
                 const sig = await this.explorerService.getSignature({
-                    fqn: officialFqn,
+                    fqn: obfuscatedFqn,
                     jarPath,
                     access: "all"
                 });
@@ -2874,7 +3535,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 +3576,7 @@ export class SourceService {
                 },
                 indexedAt: currentMeta.indexedAt,
                 durationMs: 0,
-                mappingApplied: artifact.mappingApplied ?? "official"
+                mappingApplied: artifact.mappingApplied ?? "obfuscated"
             };
         }
         const resolved = this.toResolvedArtifact(artifact);
@@ -2932,33 +3593,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 +3613,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 +3642,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 +3691,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 +3714,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 +3736,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}`]
                 });
             }
         }
@@ -3233,15 +3781,13 @@ export class SourceService {
         this.metrics.recordSearchDbRoundtrip();
         this.metrics.recordSearchRowsScanned(candidates.length);
         const result = [];
+        const glob = scope?.fileGlob ? buildGlobRegex(normalizePathStyle(scope.fileGlob)) : undefined;
         for (const symbol of candidates) {
             if (!checkPackagePrefix(symbol.filePath, scope?.packagePrefix)) {
                 continue;
             }
-            if (scope?.fileGlob) {
-                const glob = buildGlobRegex(normalizePathStyle(scope.fileGlob));
-                if (!glob.test(symbol.filePath)) {
-                    continue;
-                }
+            if (glob && !glob.test(symbol.filePath)) {
+                continue;
             }
             if (!isSymbolKind(symbol.symbolKind)) {
                 continue;
@@ -3262,13 +3808,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 +3822,6 @@ export class SourceService {
                 if (glob && !glob.test(filePath)) {
                     continue;
                 }
-                if (scopedFilesBySymbolKind && !scopedFilesBySymbolKind.has(filePath)) {
-                    continue;
-                }
                 result.push(filePath);
             }
             if (!page.nextCursor) {
@@ -3345,161 +3881,37 @@ export class SourceService {
         if (innerIndex > 0) {
             candidates.add(`${classPath.slice(0, innerIndex)}.java`);
         }
-        for (const candidate of candidates) {
-            const row = this.filesRepo.getFileContent(artifactId, candidate);
-            if (row) {
-                return row.filePath;
-            }
-        }
         const simpleName = normalizedClassName.split(/[.$]/).at(-1);
         if (!simpleName) {
             return undefined;
         }
-        const classPathBySymbol = this.symbolsRepo.findBestClassFilePath(artifactId, normalizedClassName, simpleName);
-        if (classPathBySymbol && isPackageCompatible(classPathBySymbol, classPath)) {
-            return classPathBySymbol;
-        }
-        const byName = this.filesRepo.findFirstFilePathByName(artifactId, `${simpleName}.java`);
-        if (byName && isPackageCompatible(byName, classPath)) {
-            return byName;
-        }
-        return undefined;
+        const lastSlash = classPath.lastIndexOf("/");
+        const expectedPrefix = lastSlash < 0 ? "" : classPath.slice(0, lastSlash + 1);
+        return this.filesRepo.findBestClassLookupPath(artifactId, [...candidates], normalizedClassName, simpleName, expectedPrefix);
     }
-    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 = dedupeQualityFlags([
+                ...(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,66 +3963,158 @@ 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 }
+                };
+            }
         }
-        return className;
+        if (input.mappingApplied === "obfuscated" && looksLikeDeobfuscatedClassName(input.className)) {
+            nextAction += ` ${obfuscatedNamespaceHint(input.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 resolveToOfficialMemberName(name, ownerInSourceMapping, descriptor, kind, version, mapping, sourcePriority, warnings) {
-        if (mapping === "official") {
+    async resolveToObfuscatedClassName(className, version, mapping, sourcePriority, warnings) {
+        return this.resolveClassNameForLookup({
+            className,
+            version,
+            sourceMapping: mapping,
+            targetMapping: "obfuscated",
+            sourcePriority,
+            warnings,
+            context: "bytecode lookup"
+        });
+    }
+    async resolveToObfuscatedMemberName(name, ownerInSourceMapping, descriptor, kind, version, mapping, sourcePriority, warnings) {
+        if (mapping === "obfuscated") {
             return {
                 name,
                 descriptor: kind === "method" ? descriptor : undefined
             };
         }
         try {
-            const mapped = await this.mappingService.findMapping({
-                version,
-                kind,
-                name,
-                owner: ownerInSourceMapping,
-                descriptor,
-                sourceMapping: mapping,
-                targetMapping: "official",
-                sourcePriority
-            });
+            const canResolveMethodExactly = kind === "method" &&
+                descriptor &&
+                "resolveMethodMappingExact" in this.mappingService &&
+                typeof this.mappingService.resolveMethodMappingExact === "function";
+            const mapped = canResolveMethodExactly
+                ? await this.mappingService.resolveMethodMappingExact({
+                    version,
+                    owner: ownerInSourceMapping,
+                    name,
+                    descriptor,
+                    sourceMapping: mapping,
+                    targetMapping: "obfuscated",
+                    sourcePriority
+                })
+                : await this.mappingService.findMapping({
+                    version,
+                    kind,
+                    name,
+                    owner: ownerInSourceMapping,
+                    descriptor,
+                    signatureMode: kind === "method" && !descriptor ? "name-only" : undefined,
+                    sourceMapping: mapping,
+                    targetMapping: "obfuscated",
+                    sourcePriority
+                });
+            warnings.push(...mapped.warnings);
             if (mapped.resolved && mapped.resolvedSymbol) {
                 return {
                     name: mapped.resolvedSymbol.name,
                     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}".`);
+        catch (caughtError) {
+            warnings.push(`Mapping lookup failed for ${kind} "${name}": ${caughtError instanceof Error ? caughtError.message : String(caughtError)}`);
         }
         return {
             name,
             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 +4123,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 +4161,8 @@ export class SourceService {
                     name,
                     owner: ownerFqn,
                     descriptor: kind === "method" ? descriptor : undefined,
-                    sourceMapping: "official",
-                    targetMapping: mapping,
+                    sourceMapping,
+                    targetMapping,
                     sourcePriority,
                     disambiguation: { ownerHint: targetOwner }
                 });
@@ -3677,17 +4181,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);
             }
         }));
@@ -3780,6 +4284,7 @@ export class SourceService {
             });
         });
         tx();
+        this.upsertCacheMetrics(resolved.artifactId, rebuilt.totalContentBytes, timestamp);
         log("info", "index.rebuild.done", {
             artifactId: resolved.artifactId,
             reason,
@@ -3860,7 +4365,8 @@ export class SourceService {
             files,
             symbols,
             indexedAt: new Date().toISOString(),
-            indexDurationMs: Date.now() - indexStartedAt
+            indexDurationMs: Date.now() - indexStartedAt,
+            totalContentBytes: files.reduce((sum, file) => sum + file.contentBytes, 0)
         };
     }
     getArtifact(artifactId) {
@@ -3880,7 +4386,10 @@ export class SourceService {
                 details: {
                     artifactId,
                     nextAction: "Use resolve-artifact to resolve a source artifact first.",
-                    suggestedCall: { tool: "resolve-artifact", params: { targetKind: "version", targetValue: "latest" } }
+                    suggestedCall: {
+                        tool: "resolve-artifact",
+                        params: buildResolveArtifactParams({ kind: "version", value: "latest" })
+                    }
                 }
             });
         }
@@ -3898,8 +4407,9 @@ export class SourceService {
         });
         if (existing && reason === "already_current") {
             this.metrics.recordArtifactCacheHit();
-            this.artifactsRepo.touchArtifact(resolved.artifactId, new Date().toISOString());
-            this.refreshCacheMetrics();
+            const touchedAt = new Date().toISOString();
+            this.artifactsRepo.touchArtifact(resolved.artifactId, touchedAt);
+            this.touchCacheMetrics(resolved.artifactId, touchedAt);
             return;
         }
         this.metrics.recordArtifactCacheMiss();
@@ -3910,7 +4420,6 @@ export class SourceService {
         });
         await this.rebuildAndPersistArtifactIndex(resolved, reason === "already_current" ? "missing_meta" : reason);
         this.enforceCacheLimits();
-        this.refreshCacheMetrics();
     }
     async loadFromSourceJar(sourceJarPath) {
         const files = [];
@@ -3928,21 +4437,22 @@ export class SourceService {
         return this.filesRepo.listFiles(artifactId, { limit: 1 }).items.length > 0;
     }
     enforceCacheLimits() {
-        let artifactCount = this.artifactsRepo.countArtifacts();
-        let totalBytes = this.artifactsRepo.totalContentBytes();
+        let artifactCount = this.cacheMetricsState.entries;
+        let totalBytes = this.cacheMetricsState.totalContentBytes;
         if (artifactCount <= this.config.maxArtifacts && totalBytes <= this.config.maxCacheBytes) {
             return;
         }
-        const candidates = this.artifactsRepo.listArtifactsByLruWithContentBytes(Math.max(artifactCount, 1));
+        const candidates = [...this.cacheMetricsState.lru];
         for (const candidate of candidates) {
             const shouldEvict = artifactCount > this.config.maxArtifacts || totalBytes > this.config.maxCacheBytes;
             if (!shouldEvict || artifactCount <= 1) {
-                return;
+                break;
             }
             const artifactCountBefore = artifactCount;
             const totalBytesBefore = totalBytes;
             this.filesRepo.deleteFilesForArtifact(candidate.artifactId);
             this.artifactsRepo.deleteArtifact(candidate.artifactId);
+            this.removeCacheMetrics(candidate.artifactId, false);
             artifactCount = Math.max(0, artifactCount - 1);
             totalBytes = Math.max(0, totalBytes - candidate.totalContentBytes);
             this.metrics.recordCacheEviction();
@@ -3953,6 +4463,7 @@ export class SourceService {
                 artifactBytes: candidate.totalContentBytes
             });
         }
+        this.publishCacheMetrics();
     }
     refreshCacheMetrics() {
         const cacheEntries = this.artifactsRepo.countArtifacts();
@@ -3960,13 +4471,83 @@ export class SourceService {
         const lruAccounting = this.artifactsRepo
             .listArtifactsByLruWithContentBytes(Math.max(cacheEntries, 1))
             .map((row) => ({
+            artifactId: row.artifactId,
+            totalContentBytes: row.totalContentBytes,
+            updatedAt: row.updatedAt
+        }));
+        this.cacheMetricsState = {
+            entries: cacheEntries,
+            totalContentBytes,
+            lru: lruAccounting
+        };
+        this.publishCacheMetrics();
+    }
+    touchCacheMetrics(artifactId, updatedAt) {
+        const existingIndex = this.cacheMetricsState.lru.findIndex((row) => row.artifactId === artifactId);
+        if (existingIndex < 0) {
+            this.refreshCacheMetrics();
+            return;
+        }
+        const [existing] = this.cacheMetricsState.lru.splice(existingIndex, 1);
+        if (!existing) {
+            this.refreshCacheMetrics();
+            return;
+        }
+        existing.updatedAt = updatedAt;
+        this.cacheMetricsState.lru.push(existing);
+        this.publishCacheMetrics();
+    }
+    upsertCacheMetrics(artifactId, totalContentBytes, updatedAt) {
+        const normalizedBytes = Math.max(0, Math.trunc(totalContentBytes));
+        const existingIndex = this.cacheMetricsState.lru.findIndex((row) => row.artifactId === artifactId);
+        if (existingIndex >= 0) {
+            const [existing] = this.cacheMetricsState.lru.splice(existingIndex, 1);
+            if (!existing) {
+                this.refreshCacheMetrics();
+                return;
+            }
+            this.cacheMetricsState.totalContentBytes = Math.max(0, this.cacheMetricsState.totalContentBytes - existing.totalContentBytes + normalizedBytes);
+            existing.totalContentBytes = normalizedBytes;
+            existing.updatedAt = updatedAt;
+            this.cacheMetricsState.lru.push(existing);
+        }
+        else {
+            this.cacheMetricsState.entries += 1;
+            this.cacheMetricsState.totalContentBytes += normalizedBytes;
+            this.cacheMetricsState.lru.push({
+                artifactId,
+                totalContentBytes: normalizedBytes,
+                updatedAt
+            });
+        }
+        this.cacheMetricsState.entries = this.cacheMetricsState.lru.length;
+        this.publishCacheMetrics();
+    }
+    removeCacheMetrics(artifactId, publish = true) {
+        const existingIndex = this.cacheMetricsState.lru.findIndex((row) => row.artifactId === artifactId);
+        if (existingIndex < 0) {
+            this.refreshCacheMetrics();
+            return;
+        }
+        const [existing] = this.cacheMetricsState.lru.splice(existingIndex, 1);
+        if (!existing) {
+            this.refreshCacheMetrics();
+            return;
+        }
+        this.cacheMetricsState.entries = this.cacheMetricsState.lru.length;
+        this.cacheMetricsState.totalContentBytes = Math.max(0, this.cacheMetricsState.totalContentBytes - existing.totalContentBytes);
+        if (publish) {
+            this.publishCacheMetrics();
+        }
+    }
+    publishCacheMetrics() {
+        this.metrics.setCacheEntries(this.cacheMetricsState.entries);
+        this.metrics.setCacheTotalContentBytes(this.cacheMetricsState.totalContentBytes);
+        this.metrics.setCacheArtifactByteAccounting(this.cacheMetricsState.lru.map((row) => ({
             artifact_id: row.artifactId,
             content_bytes: row.totalContentBytes,
             updated_at: row.updatedAt
-        }));
-        this.metrics.setCacheEntries(cacheEntries);
-        this.metrics.setCacheTotalContentBytes(totalContentBytes);
-        this.metrics.setCacheArtifactByteAccounting(lruAccounting);
+        })));
     }
 }
 //# sourceMappingURL=source-service.js.map