@adhisang/minecraft-modding-mcp 2.0.0 → 3.0.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,7 +172,9 @@ 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) {
@@ -97,6 +194,15 @@ function obfuscatedNamespaceHint(className) {
 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;
@@ -108,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(".");
@@ -183,6 +338,13 @@ 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 "obfuscated";
@@ -251,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) {
@@ -328,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;
@@ -354,6 +526,12 @@ function canUseIndexedSearchPath(indexedSearchEnabled, intent, match, _scope) {
     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;
@@ -380,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 = "";
@@ -556,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;
@@ -615,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
                 });
             }
@@ -633,7 +820,8 @@ 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}#net_minecraft=${candidate.hasMinecraftNamespace ? 1 : 0}`);
@@ -651,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();
@@ -762,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. " +
@@ -771,7 +1011,7 @@ export class SourceService {
                     else if (isVanillaMojang) {
                         suggestedCall = {
                             tool: "resolve-artifact",
-                            params: { targetKind: kind, targetValue: value, mapping: "obfuscated", scope: "vanilla" }
+                            params: buildResolveArtifactParams({ kind, value }, { mapping: "obfuscated", scope: "vanilla" })
                         };
                         nextAction =
                             "scope=vanilla blocks Loom cache discovery needed for mojang mapping. " +
@@ -780,7 +1020,7 @@ export class SourceService {
                     else {
                         suggestedCall = {
                             tool: "resolve-artifact",
-                            params: { targetKind: kind, targetValue: value, mapping: "obfuscated", ...(scope ? { scope } : {}) }
+                            params: buildResolveArtifactParams({ kind, value }, { mapping: "obfuscated", ...(scope ? { scope } : {}) })
                         };
                         nextAction = "Retry with mapping=obfuscated to use the runtime obfuscated namespace.";
                     }
@@ -789,6 +1029,7 @@ export class SourceService {
                         message: caughtError.message,
                         details: {
                             ...(caughtError.details ?? {}),
+                            artifactOrigin: resolved.origin,
                             searchedPaths: versionSourceDiscovery?.searchedPaths ?? [],
                             candidateArtifacts: versionSourceDiscovery?.candidateArtifacts ?? resolved.adjacentSourceCandidates ?? [],
                             recommendedCommand: this.buildVersionSourceRecoveryCommand(input.projectPath),
@@ -808,8 +1049,11 @@ 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 } : {}) })
+                            }
                         }
                     });
                 }
@@ -852,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 })
+                                }
                             }
                         });
                     }
@@ -860,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) {
@@ -890,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
             };
@@ -920,7 +1173,14 @@ export class SourceService {
             if (!query) {
                 return {
                     hits: [],
-                    mappingApplied: artifact.mappingApplied ?? "obfuscated"
+                    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);
@@ -1044,7 +1304,14 @@ export class SourceService {
             return {
                 hits: page,
                 nextCursor,
-                mappingApplied: artifact.mappingApplied ?? "obfuscated"
+                mappingApplied: artifact.mappingApplied ?? "obfuscated",
+                returnedNamespace: artifact.mappingApplied ?? "obfuscated",
+                artifactContents: this.buildArtifactContentsSummary({
+                    origin: artifact.origin,
+                    sourceJarPath: artifact.sourceJarPath,
+                    isDecompiled: artifact.isDecompiled,
+                    qualityFlags: artifact.qualityFlags
+                })
             };
         }
         finally {
@@ -1081,7 +1348,14 @@ export class SourceService {
                 content,
                 contentBytes: fullBytes,
                 truncated,
-                mappingApplied: artifact.mappingApplied ?? "obfuscated"
+                mappingApplied: artifact.mappingApplied ?? "obfuscated",
+                returnedNamespace: artifact.mappingApplied ?? "obfuscated",
+                artifactContents: this.buildArtifactContentsSummary({
+                    origin: artifact.origin,
+                    sourceJarPath: artifact.sourceJarPath,
+                    isDecompiled: artifact.isDecompiled,
+                    qualityFlags: artifact.qualityFlags
+                })
             };
         }
         finally {
@@ -1093,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 ?? "obfuscated"
+                mappingApplied: artifact.mappingApplied ?? "obfuscated",
+                artifactContents: this.buildArtifactContentsSummary({
+                    origin: artifact.origin,
+                    sourceJarPath: artifact.sourceJarPath,
+                    isDecompiled: artifact.isDecompiled,
+                    qualityFlags: artifact.qualityFlags
+                }),
+                warnings
             };
         }
         finally {
@@ -1240,6 +1528,7 @@ export class SourceService {
                 resolved: false,
                 status: "mapping_unavailable",
                 candidates: [],
+                candidateCount: 0,
                 workspaceDetection,
                 warnings
             };
@@ -1255,7 +1544,8 @@ export class SourceService {
                 descriptor: methodDescriptor,
                 sourceMapping: input.sourceMapping,
                 targetMapping: mappingApplied,
-                sourcePriority: input.sourcePriority
+                sourcePriority: input.sourcePriority,
+                maxCandidates: input.maxCandidates
             });
             return {
                 ...exact,
@@ -1285,6 +1575,7 @@ export class SourceService {
                     resolved: false,
                     status: "not_found",
                     candidates: [],
+                    candidateCount: 0,
                     workspaceDetection,
                     warnings: [...warnings, ...matrix.warnings]
                 };
@@ -1312,6 +1603,7 @@ export class SourceService {
                 status: "resolved",
                 resolvedSymbol,
                 candidates: [resolvedCandidate],
+                candidateCount: 1,
                 workspaceDetection,
                 warnings: [...warnings, ...matrix.warnings]
             };
@@ -1324,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;
@@ -1347,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]
         };
@@ -1517,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,
@@ -1690,11 +1986,39 @@ export class SourceService {
                 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, "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 };
         };
@@ -1737,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
         };
@@ -1868,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
@@ -1927,6 +2251,14 @@ export class SourceService {
             version = artifact.version;
             coordinate = artifact.coordinate;
         }
+        version = await this.resolveVersionContext({
+            version,
+            provenance,
+            coordinate,
+            projectPath: input.projectPath,
+            preferProjectVersion: input.preferProjectVersion,
+            warnings
+        });
         let activeArtifactId = artifactId;
         let activeOrigin = origin;
         let activeProvenance = provenance;
@@ -1963,7 +2295,7 @@ export class SourceService {
             activeOrigin = fallbackResolved.origin;
             activeMappingApplied = fallbackResolved.mappingApplied ?? activeMappingApplied;
             activeProvenance = fallbackResolved.provenance ?? activeProvenance;
-            activeQualityFlags = [...new Set([...(fallbackResolved.qualityFlags ?? []), "binary-fallback"])];
+            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) {
@@ -2110,8 +2442,15 @@ export class SourceService {
             artifactId: activeArtifactId,
             requestedMapping,
             mappingApplied: activeMappingApplied,
+            returnedNamespace: activeMappingApplied,
             provenance: normalizedProvenance,
             qualityFlags: activeQualityFlags,
+            artifactContents: this.buildArtifactContentsSummary({
+                origin: activeOrigin,
+                sourceJarPath: activeSourceJarPath,
+                isDecompiled: activeOrigin === "decompiled",
+                qualityFlags: activeQualityFlags
+            }),
             ...(resolvedOutputFile ? { outputFile: resolvedOutputFile } : {}),
             warnings
         };
@@ -2135,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
@@ -2149,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}.`);
         }
@@ -2177,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);
@@ -2186,16 +2529,29 @@ export class SourceService {
             provenance = artifact.provenance;
             qualityFlags = artifact.qualityFlags;
             binaryJarPath = artifact.binaryJarPath;
+            sourceJarPath = artifact.sourceJarPath;
             version = artifact.version;
+            coordinate = artifact.coordinate;
         }
+        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-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" })
+                    }
                 }
             });
         }
@@ -2206,7 +2562,7 @@ 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."
                 }
             });
         }
@@ -2288,8 +2644,15 @@ export class SourceService {
             artifactId,
             requestedMapping,
             mappingApplied,
+            returnedNamespace: requestedMapping,
             provenance: normalizedProvenance,
             qualityFlags,
+            artifactContents: this.buildArtifactContentsSummary({
+                origin,
+                sourceJarPath,
+                isDecompiled: origin === "decompiled",
+                qualityFlags
+            }),
             warnings
         };
     }
@@ -2301,7 +2664,7 @@ export class SourceService {
                 ...sharedInput,
                 source: sourceInput.source
             });
-            return this.buildValidateMixinOutput(mode, [
+            return this.applyValidateMixinOutputCompaction(this.buildValidateMixinOutput(mode, [
                 {
                     source: {
                         kind: "inline",
@@ -2309,7 +2672,7 @@ export class SourceService {
                     },
                     result: singleResult
                 }
-            ]);
+            ]), input);
         }
         if (mode === "path") {
             const resolvedPath = this.resolveMixinInputPath(sourceInput.path, "path");
@@ -2317,7 +2680,7 @@ export class SourceService {
                 ...sharedInput,
                 sourcePath: sourceInput.path
             });
-            return this.buildValidateMixinOutput(mode, [
+            return this.applyValidateMixinOutputCompaction(this.buildValidateMixinOutput(mode, [
                 {
                     source: {
                         kind: "path",
@@ -2326,7 +2689,7 @@ export class SourceService {
                     },
                     result: singleResult
                 }
-            ]);
+            ]), input);
         }
         if (mode === "paths") {
             return this.validateMixinMany(mode, sourceInput.paths.map((path) => ({
@@ -2338,7 +2701,10 @@ export class SourceService {
                 sourcePath: path
             })), input);
         }
-        const configSources = await this.resolveMixinConfigSources(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,
@@ -2353,10 +2719,94 @@ export class SourceService {
                 configPath: entry.configPath
             },
             sourcePath: entry.sourcePath
-        })), input);
+        })), 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
+            }
+        };
+    }
+    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;
+        }
+        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." });
         }
@@ -2417,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) {
@@ -2453,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",
@@ -2465,7 +2919,7 @@ export class SourceService {
             const health = await this.mappingService.checkMappingHealth({
                 version,
                 requestedMapping,
-                sourcePriority: input.sourcePriority
+                sourcePriority: currentSourcePriority
             });
             const jarAvailable = existsSync(jarPath);
             healthReport = {
@@ -2513,28 +2967,28 @@ export class SourceService {
                 }
             }
             let obfuscatedName = resolvedClassName;
-            if (requestedMapping !== "obfuscated") {
+            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: "obfuscated",
-                        sourcePriority: input.sourcePriority
+                        targetMapping: signatureLookupMapping,
+                        sourcePriority: currentSourcePriority,
+                        batchCaches: input.batchCaches
                     });
                     if (mapped.resolved && mapped.resolvedSymbol) {
                         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 obfuscated; using "${obfuscatedName}" 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: obfuscatedName, success: false, detail: "No mapping found" });
                     }
                 }
                 catch (mapErr) {
-                    warnings.push(`Mapping lookup failed for class "${resolvedClassName}"; using "${obfuscatedName}" 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: obfuscatedName, success: false, detail: mapErr instanceof Error ? mapErr.message : String(mapErr) });
                 }
@@ -2551,12 +3005,12 @@ export class SourceService {
                 let constructors = sig.constructors;
                 let methods = sig.methods;
                 let fields = sig.fields;
-                if (requestedMapping !== "obfuscated") {
+                if (requestedMapping !== signatureLookupMapping) {
                     try {
                         const [ctorResult, methodResult, fieldResult] = await Promise.all([
-                            this.remapSignatureMembers(sig.constructors, "method", version, "obfuscated", requestedMapping, input.sourcePriority, warnings),
-                            this.remapSignatureMembers(sig.methods, "method", version, "obfuscated", requestedMapping, input.sourcePriority, warnings),
-                            this.remapSignatureMembers(sig.fields, "field", version, "obfuscated", requestedMapping, input.sourcePriority, warnings)
+                            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;
@@ -2578,9 +3032,17 @@ export class SourceService {
                         }
                     }
                     catch (remapErr) {
-                        warnings.push(`Member remapping failed for "${resolvedClassName}"; falling back to obfuscated names. Member names shown may be in the obfuscated runtime namespace.`);
-                        mappingApplied = "obfuscated";
-                        resolutionTrace?.push({ target: target.className, step: "remap", input: resolvedClassName, output: "obfuscated fallback", success: false, detail: remapErr instanceof Error ? remapErr.message : String(remapErr) });
+                        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, {
@@ -2592,16 +3054,14 @@ export class SourceService {
             }
             catch (sigErr) {
                 warnings.push(`Could not load signature for class "${resolvedClassName}" (obfuscated: "${obfuscatedName}").`);
-                signatureFailedTargets.add(target.className);
                 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 });
                     }
@@ -2610,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;
@@ -2640,26 +3112,30 @@ export class SourceService {
         }
         // Build mapping chain description
         const mappingChain = [];
-        if (requestedMapping !== "obfuscated") {
-            mappingChain.push(`${requestedMapping} → obfuscated`);
-            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;
@@ -2692,7 +3168,6 @@ export class SourceService {
                 parseWarnings: filteredParseWarnings
             };
             result.unfilteredSummary = unfilteredSummary;
-            result.valid = filteredDefiniteErrors === 0;
         }
         // Apply warningCategoryFilter
         if (input.warningCategoryFilter && input.warningCategoryFilter.length > 0) {
@@ -2716,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) {
@@ -2730,10 +3204,41 @@ 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;
     }
     resolveMixinInputPath(rawPath, fieldName) {
@@ -2807,12 +3312,16 @@ export class SourceService {
         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
+                    warningMode: batchWarningMode,
+                    batchCaches
                 });
                 results.push({
                     source: entry.source,
@@ -2826,15 +3335,62 @@ export class SourceService {
                 });
             }
         }
-        return this.buildValidateMixinOutput(mode, results);
+        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 entry of results) {
             if (!entry.result) {
@@ -2847,12 +3403,18 @@ export class SourceService {
             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) {
@@ -2873,6 +3435,14 @@ export class SourceService {
             }
         }
         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)
@@ -2883,12 +3453,15 @@ export class SourceService {
             summary: {
                 total: results.length,
                 valid,
+                partial,
                 invalid,
                 processingErrors,
                 totalValidationErrors,
                 totalValidationWarnings
             },
             issueSummary,
+            provenance,
+            incompleteReasons: incompleteReasonSet.size > 0 ? [...incompleteReasonSet] : undefined,
             toolHealth,
             confidenceScore: confidenceScores.length > 0 ? Math.min(...confidenceScores) : undefined,
             warnings: [...warningSet]
@@ -3208,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;
@@ -3310,25 +3881,13 @@ 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);
     }
     async resolveBinaryFallbackArtifact(input) {
         const binaryJarPath = normalizeOptionalString(input.binaryJarPath);
@@ -3342,9 +3901,11 @@ export class SourceService {
             fallbackResolved.requestedMapping = input.requestedMapping;
             fallbackResolved.mappingApplied = input.mappingApplied;
             fallbackResolved.provenance = input.provenance;
-            fallbackResolved.qualityFlags = [
-                ...new Set([...(fallbackResolved.qualityFlags ?? []), ...input.qualityFlags, "binary-fallback"])
-            ];
+            fallbackResolved.qualityFlags = dedupeQualityFlags([
+                ...(fallbackResolved.qualityFlags ?? []),
+                ...input.qualityFlags,
+                "binary-fallback"
+            ]);
             await this.ingestIfNeeded(fallbackResolved);
             return fallbackResolved;
         }
@@ -3509,16 +4070,32 @@ export class SourceService {
             };
         }
         try {
-            const mapped = await this.mappingService.findMapping({
-                version,
-                kind,
-                name,
-                owner: ownerInSourceMapping,
-                descriptor,
-                sourceMapping: mapping,
-                targetMapping: "obfuscated",
-                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,
@@ -3527,8 +4104,8 @@ export class SourceService {
             }
             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,
@@ -3707,6 +4284,7 @@ export class SourceService {
             });
         });
         tx();
+        this.upsertCacheMetrics(resolved.artifactId, rebuilt.totalContentBytes, timestamp);
         log("info", "index.rebuild.done", {
             artifactId: resolved.artifactId,
             reason,
@@ -3787,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) {
@@ -3807,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" })
+                    }
                 }
             });
         }
@@ -3825,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();
@@ -3837,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 = [];
@@ -3855,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();
@@ -3880,6 +4463,7 @@ export class SourceService {
                 artifactBytes: candidate.totalContentBytes
             });
         }
+        this.publishCacheMetrics();
     }
     refreshCacheMetrics() {
         const cacheEntries = this.artifactsRepo.countArtifacts();
@@ -3887,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