@adhisang/minecraft-modding-mcp 3.2.0 → 4.0.0

package/dist/source-service.js

@@ -1,13 +1,16 @@
 import { createHash } from "node:crypto";
-import { existsSync } from "node:fs";
-import { access, readFile, writeFile } from "node:fs/promises";
-import { dirname, isAbsolute, resolve as resolvePath } from "node:path";
+import { existsSync, readdirSync, statSync, unlinkSync } from "node:fs";
+import { access, mkdir, open, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve as resolvePath } from "node:path";
 import fastGlob from "fast-glob";
 import { mapWithConcurrencyLimit } from "./concurrency.js";
 import { createError, ERROR_CODES, isAppError } from "./errors.js";
-import { loadConfig } from "./config.js";
+import { buildArtifactAlias, loadConfig } from "./config.js";
 import { decompileBinaryJar } from "./decompiler/vineflower.js";
 import { resolveVineflowerJar } from "./vineflower-resolver.js";
+import { remapJar } from "./tiny-remapper-service.js";
+import { resolveTinyRemapperJar } from "./tiny-remapper-resolver.js";
+import { resolveMojangTinyFile } from "./mojang-tiny-mapping-service.js";
 import { parseCoordinate } from "./maven-resolver.js";
 import { MinecraftExplorerService, modifierPrefix, parseFieldType, parseMethodDescriptor } from "./minecraft-explorer-service.js";
 import { parseMixinSource } from "./mixin-parser.js";
@@ -25,6 +28,7 @@ import { FilesRepo } from "./storage/files-repo.js";
 import { IndexMetaRepo } from "./storage/index-meta-repo.js";
 import { SymbolsRepo } from "./storage/symbols-repo.js";
 import { RuntimeMetrics } from "./observability.js";
+import { LruList } from "./lru-list.js";
 import { log } from "./logger.js";
 import { normalizePathForHost } from "./path-converter.js";
 import { buildLoaderRuntimeSearchRoots, buildVersionSourceSearchRoots, normalizeOptionalProjectPath } from "./gradle-paths.js";
@@ -148,6 +152,26 @@ function sameMixinValidationProvenance(left, right) {
         sameScopeFallback(left.scopeFallback, right.scopeFallback) &&
         sameResolutionTrace(left.resolutionTrace, right.resolutionTrace));
 }
+function annotateValidateMixinError(err, stage) {
+    if (isAppError(err)) {
+        const existing = (err.details ?? {});
+        if (typeof existing.failedStage === "string") {
+            // A nested call already tagged this error (e.g. input-validation). Preserve it.
+            return err;
+        }
+        return createError({
+            code: err.code,
+            message: err.message,
+            details: { ...existing, failedStage: stage }
+        });
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    return createError({
+        code: ERROR_CODES.INTERNAL,
+        message: `validate-mixin failed during stage "${stage}": ${message}`,
+        details: { failedStage: stage }
+    });
+}
 const INDEX_SCHEMA_VERSION = 1;
 const SYMBOL_KINDS = ["class", "interface", "enum", "record", "method", "field"];
 function isSymbolKind(value) {
@@ -768,11 +792,12 @@ export class SourceService {
     versionDiffService;
     modDecompileService;
     modSearchService;
-    cacheMetricsState = {
-        entries: 0,
-        totalContentBytes: 0,
-        lru: []
-    };
+    lru = new LruList();
+    cacheTotalContentBytes = 0;
+    remappedJarBytes = new Map();
+    /** In-flight binary-remap jobs keyed by remapped jar path so concurrent
+     * resolveArtifact calls for the same artifactId share a single tiny-remapper run. */
+    inflightRemaps = new Map();
     constructor(explicitConfig, metrics = new RuntimeMetrics()) {
         this.config = explicitConfig ?? loadConfig();
         this.metrics = metrics;
@@ -1238,6 +1263,91 @@ export class SourceService {
             : "";
         return `${prefix}./gradlew genSources --no-daemon`;
     }
+    /**
+     * Decide whether the upcoming resolveArtifact call may transparently remap a
+     * binary-only artifact (obfuscated -> mojang) and decompile it. The gate
+     * succeeds only when:
+     *   - the requested mapping is "mojang" on a still-obfuscated runtime
+     *   - tiny-remapper jar is downloadable / available locally
+     *   - the version's Mojang tiny mapping file can be produced
+     *   - checkMappingHealth reports mojang mappings are usable
+     * On any failure the variant defaults to "pass" so the legacy
+     * MAPPING_NOT_APPLIED fallback (or the existing source-backed flow) keeps
+     * its existing artifactId hash.
+     */
+    async computeBinaryRemapGate(input) {
+        const baseline = {
+            allowBinaryRemap: false,
+            mappingVariant: "pass",
+            warnings: []
+        };
+        if (input.requestedMapping !== "mojang" ||
+            input.runtimeNamesUnobfuscated ||
+            !input.version) {
+            return baseline;
+        }
+        // The Mojang tiny mapping file is only valid for vanilla Minecraft client/server jars.
+        // For coordinate / jar inputs the resolver cannot prove the artifact identity, so
+        // applying Minecraft mappings to an unrelated library/mod jar would produce a
+        // "successful" but corrupted artifact instead of the safe MAPPING_NOT_APPLIED reject.
+        // Only target.kind="version" goes through versionService.resolveVersionJar with a
+        // verified Minecraft download URL, so we restrict the gate to that input shape.
+        if (input.targetKind !== "version") {
+            return baseline;
+        }
+        let tinyRemapperJarPath;
+        try {
+            tinyRemapperJarPath = await resolveTinyRemapperJar(this.config.cacheDir, this.config.tinyRemapperJarPath);
+        }
+        catch (caughtError) {
+            log("warn", "binary-remap.gate.tiny-remapper-unavailable", {
+                version: input.version,
+                error: caughtError instanceof Error ? caughtError.message : String(caughtError)
+            });
+            return baseline;
+        }
+        let mojangTinyFilePath;
+        try {
+            const mojangTiny = await resolveMojangTinyFile(input.version, this.config);
+            mojangTinyFilePath = mojangTiny.path;
+            if (mojangTiny.warnings.length > 0) {
+                baseline.warnings.push(...mojangTiny.warnings);
+            }
+        }
+        catch (caughtError) {
+            log("warn", "binary-remap.gate.mojang-tiny-unavailable", {
+                version: input.version,
+                error: caughtError instanceof Error ? caughtError.message : String(caughtError)
+            });
+            return baseline;
+        }
+        let mojangAvailable = false;
+        try {
+            const health = await this.mappingService.checkMappingHealth({
+                version: input.version,
+                requestedMapping: "mojang",
+                sourcePriority: input.sourcePriority
+            });
+            mojangAvailable = health.mojangMappingsAvailable;
+        }
+        catch (caughtError) {
+            log("warn", "binary-remap.gate.health-check-failed", {
+                version: input.version,
+                error: caughtError instanceof Error ? caughtError.message : String(caughtError)
+            });
+            return baseline;
+        }
+        if (!mojangAvailable) {
+            return baseline;
+        }
+        return {
+            allowBinaryRemap: true,
+            mappingVariant: "mojang-remapped",
+            tinyRemapperJarPath,
+            mojangTinyFilePath,
+            warnings: baseline.warnings
+        };
+    }
     buildArtifactContentsSummary(input) {
         const sourceKind = input.isDecompiled || input.origin === "decompiled" || !normalizeOptionalString(input.sourceJarPath)
             ? "decompiled-binary"
@@ -1377,10 +1487,29 @@ export class SourceService {
                     warnings.push(`Resolved source-backed artifact from Loom cache candidate: ${versionSourceDiscovery.selectedSourceJarPath}.`);
                 }
             }
+            // The mojang binary-remap gate is only relevant when no source jar has been pre-selected.
+            // If discoverVersionSourceJar already chose a source jar, the resolver will return a
+            // source-backed artifact and applyMappingPipeline will take the source-backed branch,
+            // which never consults allowBinaryRemap. Skipping the gate avoids paying for tiny-remapper
+            // download / mojang tiny generation / mapping-health probe on healthy source-backed paths.
+            const sourceJarPreSelected = Boolean(versionSourceDiscovery?.selectedSourceJarPath);
+            const binaryRemapGate = sourceJarPreSelected
+                ? { allowBinaryRemap: false, mappingVariant: "pass", warnings: [] }
+                : await this.computeBinaryRemapGate({
+                    requestedMapping: effectiveMapping,
+                    runtimeNamesUnobfuscated,
+                    version: resolvedVersion,
+                    targetKind: kind,
+                    sourcePriority: input.sourcePriority
+                });
+            if (binaryRemapGate.warnings.length > 0) {
+                warnings.push(...binaryRemapGate.warnings);
+            }
             const resolved = await resolveSourceTargetInternal(resolvedTarget, {
                 // mojang requires source-backed artifact guarantee; force resolution to consider decompile candidate
                 // and reject later if mapping cannot be applied.
                 allowDecompile: effectiveMapping === "mojang" ? true : input.allowDecompile ?? true,
+                mappingVariant: binaryRemapGate.mappingVariant,
                 onRepoFailover: (event) => {
                     this.metrics.recordRepoFailover();
                     log("warn", "repo.failover", {
@@ -1400,7 +1529,8 @@ export class SourceService {
                     requestedMapping: effectiveMapping,
                     target: { kind, value },
                     resolved,
-                    runtimeNamesUnobfuscated
+                    runtimeNamesUnobfuscated,
+                    allowBinaryRemap: binaryRemapGate.allowBinaryRemap
                 });
             }
             catch (caughtError) {
@@ -1517,9 +1647,29 @@ export class SourceService {
                 }
             }
             resolved.qualityFlags = dedupeQualityFlags(resolved.qualityFlags);
+            // Use the resolver's canonical path (already normalizeJarPath-applied)
+            // for the readable jar token. Without this, two requests for the same
+            // artifact via a symlink path and the real path would share artifactId
+            // but produce different alias readable tokens, and setAlias rotation
+            // on the warm-cache hit would invalidate the alias returned to the
+            // earlier caller. Coordinate / version paths are already canonical:
+            // resolved.coordinate is normalized inside the resolver and
+            // resolvedVersion comes from versionService.resolveVersionJar().
+            const aliasValue = kind === "jar"
+                ? (resolved.sourceJarPath ?? resolved.binaryJarPath ?? value)
+                : value;
+            const artifactAlias = buildArtifactAlias({
+                artifactId: resolved.artifactId,
+                kind,
+                value: aliasValue,
+                mappingVariant: binaryRemapGate.mappingVariant,
+                resolvedVersion: resolvedVersion ?? resolved.version,
+                coordinate: resolved.coordinate
+            });
+            resolved.artifactAlias = artifactAlias;
             await this.ingestIfNeeded(resolved);
             let sampleEntries;
-            if (resolved.sourceJarPath) {
+            if (input.compact === false && resolved.sourceJarPath) {
                 try {
                     const javaEntries = await listJavaEntries(resolved.sourceJarPath);
                     const MAX_SAMPLE = 10;
@@ -1534,6 +1684,7 @@ export class SourceService {
             }
             return {
                 artifactId: resolved.artifactId,
+                artifactAlias,
                 origin: resolved.origin,
                 isDecompiled: resolved.isDecompiled,
                 resolvedSourceJarPath: resolved.sourceJarPath,
@@ -1578,8 +1729,8 @@ export class SourceService {
         const startedAt = Date.now();
         try {
             const artifact = this.getArtifact(input.artifactId);
-            const query = input.query.trim();
-            if (!query) {
+            const originalQuery = input.query.trim();
+            if (!originalQuery) {
                 return {
                     hits: [],
                     mappingApplied: artifact.mappingApplied ?? "obfuscated",
@@ -1594,6 +1745,80 @@ export class SourceService {
             }
             const intent = normalizeIntent(input.intent);
             const match = normalizeMatch(input.match);
+            const artifactMapping = artifact.mappingApplied ?? "obfuscated";
+            const searchWarnings = [];
+            let translatedInfo;
+            let query = originalQuery;
+            let translationPackagePrefix;
+            if (input.queryNamespace
+                && input.queryNamespace !== artifactMapping
+                && !artifact.version) {
+                searchWarnings.push(`queryNamespace=${input.queryNamespace} could not be applied because the artifact has no version recorded; namespace translation requires a version. Running literal search in ${artifactMapping} instead.`);
+            }
+            if (input.queryNamespace
+                && input.queryNamespace !== artifactMapping
+                && artifact.version) {
+                if (intent === "symbol" && originalQuery.includes(".") && /^[\w.$]+$/.test(originalQuery)) {
+                    try {
+                        const translated = await this.mappingService.findMapping({
+                            version: artifact.version,
+                            kind: "class",
+                            name: originalQuery,
+                            sourceMapping: input.queryNamespace,
+                            targetMapping: artifactMapping,
+                            sourcePriority: input.sourcePriority,
+                            signatureMode: "name-only",
+                            maxCandidates: 5
+                        });
+                        if (translated.resolved === true && translated.resolvedSymbol) {
+                            const resolvedName = translated.resolvedSymbol.symbol
+                                ?? translated.resolvedSymbol.name;
+                            if (resolvedName && resolvedName !== originalQuery) {
+                                translatedInfo = {
+                                    original: originalQuery,
+                                    translated: resolvedName,
+                                    fromNamespace: input.queryNamespace,
+                                    toNamespace: artifactMapping
+                                };
+                                // Downstream symbol search matches on simpleName only, so split
+                                // the translated FQCN into simpleName + derived packagePrefix
+                                // scope. Preserve a caller-supplied packagePrefix if present.
+                                if (resolvedName.includes(".")) {
+                                    const lastDot = resolvedName.lastIndexOf(".");
+                                    const simpleName = resolvedName.slice(lastDot + 1);
+                                    const packagePart = resolvedName.slice(0, lastDot);
+                                    query = simpleName;
+                                    if (!input.scope?.packagePrefix) {
+                                        translationPackagePrefix = packagePart;
+                                    }
+                                }
+                                else {
+                                    query = resolvedName;
+                                }
+                            }
+                        }
+                        else if (translated.status === "ambiguous") {
+                            const candidateCount = translated.candidateCount ?? translated.candidates?.length ?? 0;
+                            searchWarnings.push(`queryNamespace=${input.queryNamespace}: translation for "${originalQuery}" was ambiguous (${candidateCount} candidates); running literal search instead. Narrow the query with a more specific FQCN or call find-mapping directly.`);
+                        }
+                        else if (translated.status === "not_found") {
+                            searchWarnings.push(`queryNamespace=${input.queryNamespace}: no ${artifactMapping} mapping found for "${originalQuery}"; running literal search instead.`);
+                        }
+                        else if (translated.status === "mapping_unavailable") {
+                            searchWarnings.push(`queryNamespace=${input.queryNamespace}: mapping data unavailable for version ${artifact.version}; running literal search instead.`);
+                        }
+                        else {
+                            searchWarnings.push(`queryNamespace=${input.queryNamespace}: could not translate "${originalQuery}" to ${artifactMapping}; running literal search instead.`);
+                        }
+                    }
+                    catch (caughtError) {
+                        searchWarnings.push(`queryNamespace=${input.queryNamespace}: translation failed (${caughtError instanceof Error ? caughtError.message : String(caughtError)}); running literal search instead.`);
+                    }
+                }
+                else if (intent === "text" || intent === "path") {
+                    searchWarnings.push(`queryNamespace=${input.queryNamespace} has no effect when intent="${intent}" — ${intent} search is a literal match against the artifact's ${artifactMapping} index. Use intent="symbol" for namespace translation.`);
+                }
+            }
             if (match === "regex" && query.length > MAX_REGEX_QUERY_LENGTH) {
                 throw createError({
                     code: ERROR_CODES.INVALID_INPUT,
@@ -1607,7 +1832,9 @@ 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;
+            const scope = translationPackagePrefix
+                ? { ...(input.scope ?? {}), packagePrefix: translationPackagePrefix }
+                : input.scope;
             if (scope?.symbolKind && intent !== "symbol") {
                 throw createError({
                     code: ERROR_CODES.INVALID_INPUT,
@@ -1716,7 +1943,9 @@ export class SourceService {
                     sourceJarPath: artifact.sourceJarPath,
                     isDecompiled: artifact.isDecompiled,
                     qualityFlags: artifact.qualityFlags
-                })
+                }),
+                ...(translatedInfo ? { translatedQuery: translatedInfo } : {}),
+                ...(searchWarnings.length > 0 ? { warnings: searchWarnings } : {})
             };
         }
         finally {
@@ -2020,6 +2249,10 @@ export class SourceService {
                 warnings: [...warnings, ...matrix.warnings]
             };
         }
+        // By this point the method and class branches have already returned; only the field
+        // branch reaches the generic findMapping fallthrough, and fields do not consume
+        // signatureMode on the service side. Leave signatureMode undefined (service default =
+        // "name-only" for any accidental future non-field caller hitting this path).
         const mapped = await this.mappingService.findMapping({
             version,
             kind,
@@ -2645,15 +2878,18 @@ export class SourceService {
                 message: "className must be non-empty."
             });
         }
-        const artifactId = input.artifactId.trim();
-        if (!artifactId) {
+        const inputArtifactId = input.artifactId.trim();
+        if (!inputArtifactId) {
             throw createError({
                 code: ERROR_CODES.INVALID_INPUT,
                 message: "artifactId must be non-empty."
             });
         }
-        // Verify artifact exists
-        const artifact = this.getArtifact(artifactId);
+        // Verify artifact exists. The input may be either a 64-char artifactId or
+        // an alias; normalize to the canonical row id so downstream symbolsRepo
+        // calls (keyed by artifact_id only) do not silently miss for alias input.
+        const artifact = this.getArtifact(inputArtifactId);
+        const artifactId = artifact.artifactId;
         const limit = Math.max(1, Math.min(input.limit ?? 20, 200));
         const warnings = [];
         const isQualified = className.includes(".");
@@ -2810,6 +3046,11 @@ export class SourceService {
         }
         else {
             const artifact = this.getArtifact(artifactId);
+            // Normalize alias input to the canonical row id so downstream
+            // resolveClassFilePath / filesRepo lookups (keyed by 64-char
+            // artifact_id only) do not silently miss when the caller passed an
+            // alias from a previous resolveArtifact response.
+            artifactId = artifact.artifactId;
             origin = artifact.origin;
             requestedMapping = artifact.requestedMapping ?? requestedMapping;
             mappingApplied = artifact.mappingApplied ?? requestedMapping;
@@ -3093,6 +3334,9 @@ export class SourceService {
         }
         else {
             const artifact = this.getArtifact(artifactId);
+            // Normalize alias input to canonical row id; downstream files/symbols
+            // lookups use this id directly.
+            artifactId = artifact.artifactId;
             origin = artifact.origin;
             mappingApplied = artifact.mappingApplied ?? requestedMapping;
             provenance = artifact.provenance;
@@ -3199,6 +3443,36 @@ export class SourceService {
                 requestedMapping,
                 mappingApplied
             });
+        let decompiledFallback;
+        let decompiledMemberCounts;
+        let fallbackQualityFlags = qualityFlags;
+        if (counts.total === 0) {
+            // When the request namespace differs from the artifact namespace, the
+            // caller's memberPattern is authored against requested-namespace names
+            // (e.g. a Mojang pattern). The fallback extracts artifact-namespace
+            // names (e.g. obfuscated), so filtering by the raw pattern would
+            // silently drop every entry. Skip the filter in that case and warn.
+            const namespaceMismatch = requestedMapping !== mappingApplied;
+            const fallbackPattern = namespaceMismatch ? undefined : memberPattern;
+            const sourceFallback = this.buildDecompiledFallback(artifactId, lookupClassName, fallbackPattern, maxMembers);
+            if (sourceFallback) {
+                decompiledFallback = sourceFallback.fallback;
+                decompiledMemberCounts = sourceFallback.counts;
+                fallbackQualityFlags = dedupeQualityFlags([
+                    ...qualityFlags,
+                    "members-from-decompiled-source"
+                ]);
+                const namespaceNote = namespaceMismatch
+                    ? ` Member names are in ${mappingApplied} (artifact namespace); the request asked for ${requestedMapping}.`
+                    : "";
+                warnings.push("Bytecode member enumeration returned zero; populated decompiledFallback from decompiled source. "
+                    + "Descriptors and access modifiers are unavailable — use get-class-source for full details."
+                    + namespaceNote);
+                if (namespaceMismatch && memberPattern) {
+                    warnings.push(`memberPattern="${memberPattern}" was not applied to decompiledFallback because the artifact namespace (${mappingApplied}) differs from the requested namespace (${requestedMapping}); filter the response client-side after mapping.`);
+                }
+            }
+        }
         return {
             className,
             members: {
@@ -3215,17 +3489,83 @@ export class SourceService {
             mappingApplied,
             returnedNamespace: requestedMapping,
             provenance: normalizedProvenance,
-            qualityFlags,
+            qualityFlags: fallbackQualityFlags,
             artifactContents: this.buildArtifactContentsSummary({
                 origin,
                 sourceJarPath,
                 isDecompiled: origin === "decompiled",
-                qualityFlags
+                qualityFlags: fallbackQualityFlags
             }),
+            ...(decompiledFallback ? { decompiledFallback } : {}),
+            ...(decompiledMemberCounts ? { decompiledMemberCounts } : {}),
             warnings
         };
     }
+    buildDecompiledFallback(artifactId, lookupClassName, memberPattern, maxMembers) {
+        const filePath = this.resolveClassFilePath(artifactId, lookupClassName);
+        if (!filePath) {
+            return undefined;
+        }
+        const row = this.filesRepo.getFileContent(artifactId, filePath);
+        if (!row) {
+            return undefined;
+        }
+        const extracted = this.extractDecompiledMembers(lookupClassName, filePath, row.content);
+        const filterByPattern = (list) => {
+            if (!memberPattern) {
+                return list;
+            }
+            const lower = memberPattern.toLowerCase();
+            return list.filter((entry) => entry.name.toLowerCase().includes(lower));
+        };
+        let constructors = filterByPattern(extracted.constructors);
+        let fields = filterByPattern(extracted.fields);
+        let methods = filterByPattern(extracted.methods);
+        const totalBefore = constructors.length + fields.length + methods.length;
+        if (totalBefore === 0) {
+            return undefined;
+        }
+        let remaining = maxMembers;
+        const takeWithinLimit = (list) => {
+            if (remaining <= 0) {
+                return [];
+            }
+            const slice = list.slice(0, remaining);
+            remaining -= slice.length;
+            return slice;
+        };
+        constructors = takeWithinLimit(constructors);
+        fields = takeWithinLimit(fields);
+        methods = takeWithinLimit(methods);
+        return {
+            fallback: {
+                constructors,
+                fields,
+                methods,
+                origin: "source-extracted"
+            },
+            counts: {
+                constructors: constructors.length,
+                fields: fields.length,
+                methods: methods.length,
+                total: constructors.length + fields.length + methods.length
+            }
+        };
+    }
     async validateMixin(input) {
+        // Wrap the dispatcher so any untagged AppError coming out of path
+        // normalization, preflight discovery, or config resolution surfaces with a
+        // meaningful failedStage. annotateValidateMixinError preserves any
+        // inner-pipeline tag (resolve/mapping-health/parse/target-lookup) so only
+        // the dispatcher-level errors default to input-validation.
+        try {
+            return await this.runValidateMixinDispatcher(input);
+        }
+        catch (err) {
+            throw annotateValidateMixinError(err, "input-validation");
+        }
+    }
+    async runValidateMixinDispatcher(input) {
         const { input: sourceInput, ...sharedInput } = input;
         const mode = sourceInput.mode;
         if (mode === "inline") {
@@ -3307,6 +3647,7 @@ export class SourceService {
                 code: ERROR_CODES.INVALID_INPUT,
                 message: `No mixin config JSON files were found under project path "${input.input.path}".`,
                 details: {
+                    failedStage: "input-validation",
                     nextAction: "Use input.mode='config' with explicit configPaths[], or point input.path at the workspace root that contains *.mixins.json files."
                 }
             });
@@ -3376,37 +3717,71 @@ export class SourceService {
         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." });
-        }
-        // Resolve source from source or sourcePath
-        let source;
-        if (input.sourcePath) {
-            const normalizedSourcePath = normalizePathForHost(input.sourcePath, undefined, "sourcePath");
-            const resolvedSourcePath = isAbsolute(normalizedSourcePath)
-                ? normalizedSourcePath
-                : resolvePath(process.cwd(), normalizedSourcePath);
-            try {
-                source = await readFile(resolvedSourcePath, "utf-8");
+        // Start at input-validation so path normalization, file reads, and the
+        // simple guard checks all land under that stage. The pipeline callback
+        // shifts the stage tracker before the first non-input-validation action,
+        // and annotateValidateMixinError() preserves any nested-call stage
+        // (e.g. a deeper resolver that set failedStage="version-manifest").
+        let currentStage = "input-validation";
+        try {
+            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.",
+                    details: { failedStage: "input-validation" }
+                });
             }
-            catch (err) {
+            // Resolve source from source or sourcePath
+            let source;
+            if (input.sourcePath) {
+                const normalizedSourcePath = normalizePathForHost(input.sourcePath, undefined, "sourcePath");
+                const resolvedSourcePath = isAbsolute(normalizedSourcePath)
+                    ? normalizedSourcePath
+                    : resolvePath(process.cwd(), normalizedSourcePath);
+                try {
+                    source = await readFile(resolvedSourcePath, "utf-8");
+                }
+                catch (err) {
+                    throw createError({
+                        code: ERROR_CODES.INVALID_INPUT,
+                        message: `Could not read sourcePath "${input.sourcePath}" (resolved to "${resolvedSourcePath}"):` +
+                            ` ${err instanceof Error ? err.message : String(err)}`,
+                        details: { failedStage: "input-validation" }
+                    });
+                }
+            }
+            else {
+                source = input.source ?? "";
+            }
+            if (!source.trim()) {
                 throw createError({
                     code: ERROR_CODES.INVALID_INPUT,
-                    message: `Could not read sourcePath "${input.sourcePath}" (resolved to "${resolvedSourcePath}"):` +
-                        ` ${err instanceof Error ? err.message : String(err)}`
+                    message: "source must be non-empty.",
+                    details: { failedStage: "input-validation" }
                 });
             }
+            return await this.runValidateMixinPipeline({
+                input,
+                version,
+                source,
+                requestedScope,
+                currentSourcePriority,
+                initialSourcePriority,
+                onStage: (stage) => { currentStage = stage; }
+            });
         }
-        else {
-            source = input.source ?? "";
-        }
-        if (!source.trim()) {
-            throw createError({ code: ERROR_CODES.INVALID_INPUT, message: "source must be non-empty." });
+        catch (err) {
+            throw annotateValidateMixinError(err, currentStage);
         }
+    }
+    async runValidateMixinPipeline(ctx) {
+        const { input, source, requestedScope, currentSourcePriority, initialSourcePriority, onStage } = ctx;
+        let { version } = ctx;
+        onStage("resolve");
         const warnings = [];
         let mappingAutoDetected = false;
         // Auto-detect mapping from project config when not explicitly provided (or when preferProjectMapping is set)
@@ -3487,6 +3862,7 @@ export class SourceService {
             };
         }
         // Health check: probe mapping infrastructure
+        onStage("mapping-health");
         let healthReport;
         try {
             const health = await this.mappingService.checkMappingHealth({
@@ -3508,10 +3884,24 @@ export class SourceService {
                 ]
             };
         }
-        catch {
-            // Health check failed — proceed without it
+        catch (err) {
+            // Probe itself failed — surface the degradation instead of swallowing it
+            // silently, so quickSummary and toolHealth reflect the unknown-health
+            // state rather than looking clean.
+            const reason = err instanceof Error ? err.message : String(err);
+            healthReport = {
+                jarAvailable: existsSync(jarPath),
+                jarPath,
+                mojangMappingsAvailable: false,
+                tinyMappingsAvailable: false,
+                memberRemapAvailable: false,
+                overallHealthy: false,
+                degradations: [`Mapping health probe failed: ${reason}`]
+            };
         }
+        onStage("parse");
         const parsed = parseMixinSource(source);
+        onStage("target-lookup");
         const targetMembers = new Map();
         const mappingFailedTargets = new Set();
         const remapFailedMembers = new Map();
@@ -3772,8 +4162,12 @@ export class SourceService {
             if (result.structuredWarnings.length === 0)
                 result.structuredWarnings = undefined;
         }
-        // Apply compact report mode
+        // Apply compact report mode. refreshMixinValidationOutcome reads
+        // result.toolHealth / result.provenance when it rebuilds quickSummary, so
+        // refresh BEFORE stripping those fields; otherwise compact mode would
+        // silently drop the mapping-health-degraded and scope-fallback notes.
         if (input.reportMode === "compact") {
+            refreshMixinValidationOutcome(result);
             result.resolvedMembers = undefined;
             result.structuredWarnings = undefined;
             result.aggregatedWarnings = undefined;
@@ -3783,7 +4177,9 @@ export class SourceService {
                 result.provenance.resolutionTrace = undefined;
             }
         }
-        refreshMixinValidationOutcome(result);
+        else {
+            refreshMixinValidationOutcome(result);
+        }
         if (this.shouldRetryValidateMixinWithMavenFirst(input, result)) {
             const retryWarning = `Retrying validate-mixin with sourcePriority="maven-first" after partial validation using "${currentSourcePriority}".`;
             try {
@@ -3806,7 +4202,14 @@ export class SourceService {
                         `Validation retried with sourcePriority "maven-first" after partial result from "${currentSourcePriority}".`
                     ];
                 }
-                return refreshMixinValidationOutcome(retried);
+                // The recursive validateMixinSingle call already produced final summary /
+                // status / quickSummary. The only mutations above are warnings and
+                // provenance.resolutionNotes, which quickSummary does not read. Calling
+                // refreshMixinValidationOutcome(retried) here would rebuild quickSummary
+                // against the already-compacted `retried.toolHealth === undefined`, which
+                // silently strips the mapping-health-degraded note we just preserved in
+                // the compact branch above.
+                return retried;
             }
             catch (retryErr) {
                 result.warnings.unshift(`${retryWarning} Retry failed: ${retryErr instanceof Error ? retryErr.message : String(retryErr)}`);
@@ -3840,7 +4243,8 @@ export class SourceService {
             catch (err) {
                 throw createError({
                     code: ERROR_CODES.INVALID_INPUT,
-                    message: `Could not read/parse mixin config "${rawConfigPath}": ${err instanceof Error ? err.message : String(err)}`
+                    message: `Could not read/parse mixin config "${rawConfigPath}": ${err instanceof Error ? err.message : String(err)}`,
+                    details: { failedStage: "input-validation" }
                 });
             }
             const pkg = configJson.package ?? "";
@@ -4291,7 +4695,12 @@ export class SourceService {
         }
         return result;
     }
+    recordToolCall(tool, durationMs) {
+        this.metrics.recordToolCall(tool, durationMs);
+    }
     getRuntimeMetrics() {
+        this.snapshotLruAccounting();
+        this.metrics.setMappingResolutionCacheStats(this.mappingService.resolutionCacheStats);
         return this.metrics.snapshot();
     }
     async indexArtifact(input) {
@@ -4619,6 +5028,117 @@ export class SourceService {
         }
         return outputParts.join("\n");
     }
+    extractDecompiledMembers(className, filePath, content) {
+        const symbols = extractSymbolsFromSource(filePath, content);
+        const simpleName = className.split(/[.$]/).at(-1) ?? className;
+        const lines = content.split(/\r?\n/);
+        const body = this.computeBraceRange(lines, symbols, simpleName);
+        if (!body) {
+            return { constructors: [], fields: [], methods: [] };
+        }
+        const depths = this.computeLineBraceDepths(lines);
+        const baseDepth = depths[body.declarationLine - 1] ?? 0;
+        const nestedRanges = this.computeNestedTypeRanges(lines, symbols, body);
+        const constructors = [];
+        const fields = [];
+        const methods = [];
+        for (const symbol of symbols) {
+            if (symbol.line <= body.declarationLine || symbol.line > body.endLine) {
+                continue;
+            }
+            if (nestedRanges.some((range) => symbol.line >= range.declarationLine && symbol.line <= range.endLine)) {
+                continue;
+            }
+            const lineDepth = depths[symbol.line - 1] ?? baseDepth;
+            // Declarations directly inside the class body sit at baseDepth+1; anything
+            // deeper is a method/constructor body, an initializer block, etc.
+            if (lineDepth !== baseDepth + 1) {
+                continue;
+            }
+            if (symbol.symbolKind === "method") {
+                if (symbol.symbolName === simpleName) {
+                    constructors.push({ name: "<init>", line: symbol.line, kind: "constructor" });
+                }
+                else {
+                    methods.push({ name: symbol.symbolName, line: symbol.line, kind: "method" });
+                }
+            }
+            else if (symbol.symbolKind === "field") {
+                fields.push({ name: symbol.symbolName, line: symbol.line, kind: "field" });
+            }
+        }
+        return { constructors, fields, methods };
+    }
+    computeLineBraceDepths(lines) {
+        const depths = new Array(lines.length).fill(0);
+        let depth = 0;
+        for (let i = 0; i < lines.length; i += 1) {
+            // Entry depth for this line = depth observed before any brace on it.
+            depths[i] = depth;
+            const stripped = (lines[i] ?? "")
+                .replace(/\/\/.*/g, "")
+                .replace(/"(?:\\.|[^"\\])*"/g, "\"\"")
+                .replace(/'(?:\\.|[^'\\])*'/g, "''");
+            for (const char of stripped) {
+                if (char === "{") {
+                    depth += 1;
+                }
+                else if (char === "}") {
+                    depth -= 1;
+                }
+            }
+        }
+        return depths;
+    }
+    computeBraceRange(lines, symbols, simpleName) {
+        const classSymbol = symbols.find((symbol) => (symbol.symbolKind === "class" || symbol.symbolKind === "interface"
+            || symbol.symbolKind === "enum" || symbol.symbolKind === "record")
+            && symbol.symbolName === simpleName);
+        if (!classSymbol) {
+            return undefined;
+        }
+        return this.scanBraceRange(lines, classSymbol.line);
+    }
+    scanBraceRange(lines, declarationLine) {
+        let depth = 0;
+        let started = false;
+        for (let i = declarationLine - 1; i < lines.length; i += 1) {
+            const stripped = (lines[i] ?? "")
+                .replace(/\/\/.*/g, "")
+                .replace(/"(?:\\.|[^"\\])*"/g, "\"\"");
+            for (const char of stripped) {
+                if (char === "{") {
+                    depth += 1;
+                    started = true;
+                }
+                else if (char === "}") {
+                    depth -= 1;
+                    if (started && depth === 0) {
+                        return { declarationLine, endLine: i + 1 };
+                    }
+                }
+            }
+        }
+        return { declarationLine, endLine: lines.length };
+    }
+    computeNestedTypeRanges(lines, symbols, outerBody) {
+        const ranges = [];
+        for (const candidate of symbols) {
+            if (candidate.symbolKind !== "class" && candidate.symbolKind !== "interface"
+                && candidate.symbolKind !== "enum" && candidate.symbolKind !== "record") {
+                continue;
+            }
+            if (candidate.line <= outerBody.declarationLine || candidate.line > outerBody.endLine) {
+                continue;
+            }
+            if (ranges.some((range) => candidate.line >= range.declarationLine && candidate.line <= range.endLine)) {
+                continue;
+            }
+            const nestedRange = this.scanBraceRange(lines, candidate.line);
+            ranges.push(nestedRange);
+        }
+        return ranges;
+    }
     resolveClassFilePath(artifactId, className) {
         const normalizedClassName = className.trim();
         const classPath = classNameToClassPath(normalizedClassName);
@@ -4871,7 +5391,15 @@ export class SourceService {
                     name,
                     owner: ownerInSourceMapping,
                     descriptor,
-                    signatureMode: kind === "method" && !descriptor ? "name-only" : undefined,
+                    // When we do have a descriptor this path is an exact lookup (the resolveMethodMappingExact
+                    // fast path is chosen instead whenever possible). findMapping's service-layer default is
+                    // "name-only" to match the public tool schema, so we must opt in to strict semantics here
+                    // to preserve the descriptor-aware overload selection this caller relies on.
+                    signatureMode: kind === "method"
+                        ? descriptor
+                            ? "exact"
+                            : "name-only"
+                        : undefined,
                     sourceMapping: mapping,
                     targetMapping: "obfuscated",
                     sourcePriority
@@ -4883,6 +5411,33 @@ export class SourceService {
                     descriptor: kind === "method" ? mapped.resolvedSymbol.descriptor ?? descriptor : undefined
                 };
             }
+            // resolveMethodMappingExact still rejects partial descriptor projections, so a
+            // Mojang / Yarn method whose descriptor mixes a remapped Minecraft class with a JDK
+            // type (e.g. `(L...ItemStack;Ljava/lang/String;)V`) bottoms out as unresolved /
+            // mapping_unavailable here even though `findMapping` with signatureMode="exact" would
+            // accept the partially projected descriptor. Fall back to `findMapping` before giving
+            // up so downstream paths (access-widener remap, trace-symbol-lifecycle, signature
+            // member remap) do not silently miss real methods.
+            if (canResolveMethodExactly && (mapped.status === "not_found" || mapped.status === "mapping_unavailable")) {
+                const fallbackMapped = await this.mappingService.findMapping({
+                    version,
+                    kind,
+                    name,
+                    owner: ownerInSourceMapping,
+                    descriptor,
+                    signatureMode: "exact",
+                    sourceMapping: mapping,
+                    targetMapping: "obfuscated",
+                    sourcePriority
+                });
+                warnings.push(...fallbackMapped.warnings);
+                if (fallbackMapped.resolved && fallbackMapped.resolvedSymbol) {
+                    return {
+                        name: fallbackMapped.resolvedSymbol.name,
+                        descriptor: kind === "method" ? fallbackMapped.resolvedSymbol.descriptor ?? descriptor : undefined
+                    };
+                }
+            }
             warnings.push(`Could not map ${kind} "${name}" from ${mapping} to obfuscated.`);
         }
         catch (caughtError) {
@@ -5019,6 +5574,10 @@ export class SourceService {
                     name,
                     owner: ownerFqn,
                     descriptor: kind === "method" ? descriptor : undefined,
+                    // Access-widener / access-transformer remap runs after validation has accepted
+                    // the descriptor as authoritative, so preserve exact overload matching even
+                    // though the descriptorHint path also exists for ambiguity fallback.
+                    signatureMode: kind === "method" && descriptor ? "exact" : undefined,
                     sourceMapping,
                     targetMapping,
                     sourcePriority,
@@ -5100,6 +5659,7 @@ export class SourceService {
     toResolvedArtifact(artifact) {
         return {
             artifactId: artifact.artifactId,
+            artifactAlias: artifact.alias,
             artifactSignature: artifact.artifactSignature ?? this.fallbackArtifactSignature(artifact.artifactId),
             origin: artifact.origin,
             binaryJarPath: artifact.binaryJarPath,
@@ -5122,6 +5682,7 @@ export class SourceService {
         const tx = this.db.transaction(() => {
             this.artifactsRepo.upsertArtifact({
                 artifactId: resolved.artifactId,
+                alias: resolved.artifactAlias,
                 origin: resolved.origin,
                 coordinate: resolved.coordinate,
                 version: resolved.version,
@@ -5173,10 +5734,20 @@ export class SourceService {
             files = await this.loadFromSourceJar(resolved.sourceJarPath);
         }
         else if (resolved.binaryJarPath) {
+            const decompileInputJarPath = await this.maybeRemapBinaryForMojang(resolved);
+            // When the binary jar was remapped from obfuscated to mojang, swap the resolved
+            // artifact's binaryJarPath to the remapped jar so downstream bytecode consumers
+            // (getClassMembers, validateMixin) look up mojang names in the mojang jar — not
+            // the original obfuscated jar. Persistence in upsertArtifact happens after this
+            // function returns, so the swap reaches both the database row and the
+            // resolveArtifact response.
+            if (decompileInputJarPath !== resolved.binaryJarPath) {
+                resolved.binaryJarPath = decompileInputJarPath;
+            }
             const vineflowerPath = await resolveVineflowerJar(this.config.cacheDir, this.config.vineflowerJarPath);
             const decompileStartedAt = Date.now();
             try {
-                const decompileResult = await decompileBinaryJar(resolved.binaryJarPath, this.config.cacheDir, {
+                const decompileResult = await decompileBinaryJar(decompileInputJarPath, this.config.cacheDir, {
                     vineflowerJarPath: vineflowerPath,
                     artifactIdCandidate: resolved.artifactId,
                     timeoutMs: 120_000,
@@ -5278,6 +5849,30 @@ export class SourceService {
             meta
         });
         if (existing && reason === "already_current") {
+            // Mojang binary-remap reconciliation on the warm cache hit path:
+            // resolveSourceTargetInternal always returns the original binary jar
+            // (resolver does not know about prior remap output), so without this
+            // step a warm-cache resolve would return mappingApplied="mojang"
+            // alongside binaryJarPath pointing at the obfuscated client jar.
+            // maybeRemapBinaryForMojang short-circuits on a healthy cache hit
+            // (existsSync + ZIP magic) and re-remaps when the cache is missing
+            // or corrupted, so this also recovers from out-of-band cache loss.
+            const transformChain = resolved.provenance?.transformChain ?? [];
+            if (transformChain.includes("binary-remap:obf->mojang") && resolved.binaryJarPath) {
+                const reconciledBinaryJarPath = await this.maybeRemapBinaryForMojang(resolved);
+                if (reconciledBinaryJarPath !== resolved.binaryJarPath) {
+                    resolved.binaryJarPath = reconciledBinaryJarPath;
+                }
+            }
+            // Backfill / rotate alias on the warm-cache path. Without this, schema-v4
+            // migrated rows (alias=NULL) and rows whose alias parameters changed since
+            // the last upsert would return an artifactAlias from resolveArtifact that
+            // does not resolve back via getArtifact(alias), breaking the 3.1b lookup
+            // contract. UNIQUE conflicts here are caller bugs (two distinct artifactIds
+            // colliding on alias) and surface as DB errors rather than silent drift.
+            if (resolved.artifactAlias && existing.alias !== resolved.artifactAlias) {
+                this.artifactsRepo.setAlias(resolved.artifactId, resolved.artifactAlias);
+            }
             this.metrics.recordArtifactCacheHit();
             const touchedAt = new Date().toISOString();
             this.artifactsRepo.touchArtifact(resolved.artifactId, touchedAt);
@@ -5293,6 +5888,164 @@ export class SourceService {
         await this.rebuildAndPersistArtifactIndex(resolved, reason === "already_current" ? "missing_meta" : reason);
         this.enforceCacheLimits();
     }
+    /**
+     * If the resolved artifact's transformChain promised an "obf -> mojang"
+     * binary remap, run tiny-remapper now and return the remapped jar path.
+     * Otherwise return the original binaryJarPath unchanged.
+     *
+     * Cache safety: writes to a per-attempt temp file then atomic-renames into
+     * <cacheDir>/remapped/<artifactId>.jar. A per-target inflight Promise map
+     * collapses concurrent calls so two simultaneous resolveArtifact calls for
+     * the same artifactId share one tiny-remapper run instead of racing on the
+     * same output path.
+     */
+    async maybeRemapBinaryForMojang(resolved) {
+        const binaryJarPath = resolved.binaryJarPath;
+        if (!binaryJarPath) {
+            throw createError({
+                code: ERROR_CODES.SOURCE_NOT_FOUND,
+                message: "Cannot run binary remap: resolved artifact has no binary jar path.",
+                details: { artifactId: resolved.artifactId }
+            });
+        }
+        const transformChain = resolved.provenance?.transformChain ?? [];
+        if (!transformChain.includes("binary-remap:obf->mojang")) {
+            return binaryJarPath;
+        }
+        if (!resolved.version) {
+            throw createError({
+                code: ERROR_CODES.MAPPING_NOT_APPLIED,
+                message: "Binary remap promised but artifact has no resolved Minecraft version.",
+                details: {
+                    artifactId: resolved.artifactId,
+                    binaryJarPath,
+                    nextAction: "Use target.kind=\"version\" so the remap pipeline can locate Mojang mappings."
+                }
+            });
+        }
+        const remappedDir = join(this.config.cacheDir, "remapped");
+        const remappedJarPath = join(remappedDir, `${resolved.artifactId}.jar`);
+        if (existsSync(remappedJarPath)) {
+            // Validate the cached jar is at least structurally a ZIP (`PK\x03\x04`) and
+            // non-empty before reusing. If a prior atomic-rename window was interrupted
+            // or the cache file was hand-edited, drop it and re-remap rather than
+            // silently feeding a corrupt jar into Vineflower.
+            if (await this.isUsableJarFile(remappedJarPath)) {
+                await this.recordRemappedJarBytesFromDisk(resolved.artifactId, remappedJarPath);
+                return remappedJarPath;
+            }
+            log("warn", "binary-remap.cache.evict-corrupt", {
+                artifactId: resolved.artifactId,
+                remappedJarPath
+            });
+            try {
+                await unlink(remappedJarPath);
+            }
+            catch {
+                // ignore: race with another process or already-deleted file.
+            }
+            this.releaseRemappedJarBytes(resolved.artifactId);
+        }
+        const inflight = this.inflightRemaps.get(remappedJarPath);
+        if (inflight) {
+            return inflight;
+        }
+        const remapPromise = this.runBinaryRemap({
+            version: resolved.version,
+            inputJar: binaryJarPath,
+            remappedDir,
+            remappedJarPath
+        });
+        this.inflightRemaps.set(remappedJarPath, remapPromise);
+        try {
+            const path = await remapPromise;
+            await this.recordRemappedJarBytesFromDisk(resolved.artifactId, path);
+            return path;
+        }
+        finally {
+            this.inflightRemaps.delete(remappedJarPath);
+        }
+    }
+    async recordRemappedJarBytesFromDisk(artifactId, path) {
+        try {
+            const fileStat = await stat(path);
+            this.recordRemappedJarBytes(artifactId, fileStat.size);
+        }
+        catch {
+            // best-effort: accounting will be rebuilt on the next refreshCacheMetrics.
+        }
+    }
+    /**
+     * Best-effort structural check that `path` is a non-empty file beginning with
+     * the ZIP local-file-header magic (`50 4B 03 04`). Used to drop partial /
+     * corrupt remap-cache entries before they reach Vineflower. False positives
+     * are acceptable (Vineflower will surface a clearer error); false negatives
+     * are not (a corrupt cache hit must be evicted).
+     */
+    async isUsableJarFile(path) {
+        try {
+            const stats = await stat(path);
+            if (!stats.isFile() || stats.size < 4) {
+                return false;
+            }
+        }
+        catch {
+            return false;
+        }
+        let handle;
+        try {
+            handle = await open(path, "r");
+            const header = Buffer.alloc(4);
+            const { bytesRead } = await handle.read(header, 0, 4, 0);
+            return bytesRead === 4 && header[0] === 0x50 && header[1] === 0x4b && header[2] === 0x03 && header[3] === 0x04;
+        }
+        catch {
+            return false;
+        }
+        finally {
+            await handle?.close().catch(() => undefined);
+        }
+    }
+    async runBinaryRemap(input) {
+        const tinyRemapperJarPath = await resolveTinyRemapperJar(this.config.cacheDir, this.config.tinyRemapperJarPath);
+        const mojangTiny = await resolveMojangTinyFile(input.version, this.config);
+        await mkdir(input.remappedDir, { recursive: true });
+        const tempPath = `${input.remappedJarPath}.tmp.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}`;
+        const remapStartedAt = Date.now();
+        try {
+            await remapJar(tinyRemapperJarPath, {
+                inputJar: input.inputJar,
+                outputJar: tempPath,
+                mappingsFile: mojangTiny.path,
+                fromNamespace: "obfuscated",
+                toNamespace: "mojang",
+                timeoutMs: this.config.remapTimeoutMs,
+                maxMemoryMb: this.config.remapMaxMemoryMb
+            });
+            const tempStats = await stat(tempPath);
+            if (tempStats.size === 0) {
+                throw createError({
+                    code: ERROR_CODES.REMAP_FAILED,
+                    message: "tiny-remapper produced an empty output jar.",
+                    details: { inputJar: input.inputJar, tempPath }
+                });
+            }
+            await rename(tempPath, input.remappedJarPath);
+            return input.remappedJarPath;
+        }
+        catch (caughtError) {
+            try {
+                await unlink(tempPath);
+            }
+            catch {
+                // tempPath may not exist if remapJar failed before writing anything; ignore.
+            }
+            throw caughtError;
+        }
+        finally {
+            this.metrics.recordDuration("binary_remap_duration_ms", Date.now() - remapStartedAt);
+        }
+    }
     async loadFromSourceJar(sourceJarPath) {
         const files = [];
         for await (const entry of iterateJavaEntriesAsUtf8(sourceJarPath, this.config.maxContentBytes)) {
@@ -5308,13 +6061,55 @@ export class SourceService {
     hasAnyFiles(artifactId) {
         return this.filesRepo.listFiles(artifactId, { limit: 1 }).items.length > 0;
     }
+    /**
+     * Best-effort cleanup of `<cacheDir>/remapped/<artifactId>.jar` written by
+     * `maybeRemapBinaryForMojang`. Called from cache-eviction paths so the
+     * Mojang-remapped binary jar does not outlive the artifact row that owns it.
+     * Also releases the jar's bytes from `cacheTotalContentBytes`. Errors are
+     * swallowed: orphaned jars remain visible to `manage-cache` under the
+     * `binary-remap` cache kind and can be reclaimed there.
+     */
+    unlinkRemappedJarForArtifact(artifactId) {
+        this.releaseRemappedJarBytes(artifactId);
+        const remappedJarPath = join(this.config.cacheDir, "remapped", `${artifactId}.jar`);
+        try {
+            if (existsSync(remappedJarPath)) {
+                unlinkSync(remappedJarPath);
+            }
+        }
+        catch {
+            // ignore: orphaned jar is still reclaimable via manage-cache binary-remap kind.
+        }
+    }
+    /**
+     * Add the remapped jar's on-disk size to `cacheTotalContentBytes` so the
+     * `enforceCacheLimits` byte gate sees the jar before deciding to evict.
+     * Without this, a Mojang-remapped client jar (tens of MB) can accumulate
+     * silently while the indexed-source byte total stays below `maxCacheBytes`.
+     */
+    recordRemappedJarBytes(artifactId, sizeBytes) {
+        const normalized = Math.max(0, Math.trunc(sizeBytes));
+        const existing = this.remappedJarBytes.get(artifactId) ?? 0;
+        this.cacheTotalContentBytes = Math.max(0, this.cacheTotalContentBytes - existing + normalized);
+        this.remappedJarBytes.set(artifactId, normalized);
+        this.publishCacheMetrics();
+    }
+    releaseRemappedJarBytes(artifactId) {
+        const existing = this.remappedJarBytes.get(artifactId);
+        if (!existing) {
+            return;
+        }
+        this.cacheTotalContentBytes = Math.max(0, this.cacheTotalContentBytes - existing);
+        this.remappedJarBytes.delete(artifactId);
+        this.publishCacheMetrics();
+    }
     enforceCacheLimits() {
-        let artifactCount = this.cacheMetricsState.entries;
-        let totalBytes = this.cacheMetricsState.totalContentBytes;
+        let artifactCount = this.lru.size;
+        let totalBytes = this.cacheTotalContentBytes;
         if (artifactCount <= this.config.maxArtifacts && totalBytes <= this.config.maxCacheBytes) {
             return;
         }
-        const candidates = [...this.cacheMetricsState.lru];
+        const candidates = this.lru.toArray();
         for (const candidate of candidates) {
             const shouldEvict = artifactCount > this.config.maxArtifacts || totalBytes > this.config.maxCacheBytes;
             if (!shouldEvict || artifactCount <= 1) {
@@ -5322,17 +6117,19 @@ export class SourceService {
             }
             const artifactCountBefore = artifactCount;
             const totalBytesBefore = totalBytes;
-            this.filesRepo.deleteFilesForArtifact(candidate.artifactId);
-            this.artifactsRepo.deleteArtifact(candidate.artifactId);
-            this.removeCacheMetrics(candidate.artifactId, false);
+            const remappedBytesForCandidate = this.remappedJarBytes.get(candidate.key) ?? 0;
+            this.filesRepo.deleteFilesForArtifact(candidate.key);
+            this.artifactsRepo.deleteArtifact(candidate.key);
+            this.unlinkRemappedJarForArtifact(candidate.key);
+            this.removeCacheMetrics(candidate.key, false);
             artifactCount = Math.max(0, artifactCount - 1);
-            totalBytes = Math.max(0, totalBytes - candidate.totalContentBytes);
+            totalBytes = Math.max(0, totalBytes - candidate.value.totalContentBytes - remappedBytesForCandidate);
             this.metrics.recordCacheEviction();
             log("warn", "cache.evict", {
-                artifactId: candidate.artifactId,
+                artifactId: candidate.key,
                 artifactCountBefore,
                 totalBytesBefore,
-                artifactBytes: candidate.totalContentBytes
+                artifactBytes: candidate.value.totalContentBytes + remappedBytesForCandidate
             });
         }
         this.publishCacheMetrics();
@@ -5340,82 +6137,94 @@ export class SourceService {
     refreshCacheMetrics() {
         const cacheEntries = this.artifactsRepo.countArtifacts();
         const totalContentBytes = this.artifactsRepo.totalContentBytes();
-        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
-        };
+        const lruAccounting = this.artifactsRepo.listArtifactsByLruWithContentBytes(Math.max(cacheEntries, 1));
+        this.lru.clear();
+        for (const row of lruAccounting) {
+            this.lru.upsert(row.artifactId, {
+                totalContentBytes: row.totalContentBytes,
+                updatedAt: row.updatedAt
+            });
+        }
+        this.remappedJarBytes.clear();
+        let remappedTotal = 0;
+        const remappedDir = join(this.config.cacheDir, "remapped");
+        if (existsSync(remappedDir)) {
+            // Only count remapped jars whose owning artifact is still in the LRU set.
+            // Orphaned jars (artifact deleted, prior unlink lost a race, externally
+            // placed) stay visible to manage-cache under the `binary-remap` kind
+            // for prune, but must not be folded into `cacheTotalContentBytes` here:
+            // enforceCacheLimits cannot evict them, so counting their bytes would
+            // force unrelated live artifacts to be evicted to chase orphan bytes.
+            const liveArtifactIds = new Set(this.lru.toArray().map((entry) => entry.key));
+            try {
+                for (const entry of readdirSync(remappedDir, { withFileTypes: true })) {
+                    if (!entry.isFile() || !entry.name.endsWith(".jar")) {
+                        continue;
+                    }
+                    const artifactId = entry.name.slice(0, -".jar".length);
+                    if (!liveArtifactIds.has(artifactId)) {
+                        continue;
+                    }
+                    try {
+                        const fileStat = statSync(join(remappedDir, entry.name));
+                        const size = Math.max(0, Math.trunc(fileStat.size));
+                        this.remappedJarBytes.set(artifactId, size);
+                        remappedTotal += size;
+                    }
+                    catch {
+                        // ignore stat failure on a single jar; total stays best-effort.
+                    }
+                }
+            }
+            catch {
+                // ignore listing failure; remapped accounting stays empty until next remap.
+            }
+        }
+        this.cacheTotalContentBytes = totalContentBytes + remappedTotal;
         this.publishCacheMetrics();
     }
     touchCacheMetrics(artifactId, updatedAt) {
-        const existingIndex = this.cacheMetricsState.lru.findIndex((row) => row.artifactId === artifactId);
-        if (existingIndex < 0) {
+        const entry = this.lru.touch(artifactId);
+        if (!entry) {
             this.refreshCacheMetrics();
             return;
         }
-        const [existing] = this.cacheMetricsState.lru.splice(existingIndex, 1);
-        if (!existing) {
-            this.refreshCacheMetrics();
-            return;
-        }
-        existing.updatedAt = updatedAt;
-        this.cacheMetricsState.lru.push(existing);
+        entry.updatedAt = updatedAt;
         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);
+        const existing = this.lru.remove(artifactId);
+        if (existing) {
+            this.cacheTotalContentBytes = Math.max(0, this.cacheTotalContentBytes - existing.totalContentBytes + normalizedBytes);
         }
         else {
-            this.cacheMetricsState.entries += 1;
-            this.cacheMetricsState.totalContentBytes += normalizedBytes;
-            this.cacheMetricsState.lru.push({
-                artifactId,
-                totalContentBytes: normalizedBytes,
-                updatedAt
-            });
+            this.cacheTotalContentBytes += normalizedBytes;
         }
-        this.cacheMetricsState.entries = this.cacheMetricsState.lru.length;
+        this.lru.upsert(artifactId, { totalContentBytes: normalizedBytes, updatedAt });
         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);
+        const existing = this.lru.remove(artifactId);
         if (!existing) {
             this.refreshCacheMetrics();
             return;
         }
-        this.cacheMetricsState.entries = this.cacheMetricsState.lru.length;
-        this.cacheMetricsState.totalContentBytes = Math.max(0, this.cacheMetricsState.totalContentBytes - existing.totalContentBytes);
+        this.cacheTotalContentBytes = Math.max(0, this.cacheTotalContentBytes - existing.totalContentBytes);
         if (publish) {
             this.publishCacheMetrics();
         }
     }
     publishCacheMetrics() {
-        this.metrics.setCacheEntries(this.cacheMetricsState.entries);
-        this.metrics.setCacheTotalContentBytes(this.cacheMetricsState.totalContentBytes);
-        this.metrics.setCacheArtifactByteAccountingRef(this.cacheMetricsState.lru);
+        this.metrics.setCacheEntries(this.lru.size);
+        this.metrics.setCacheTotalContentBytes(this.cacheTotalContentBytes);
+    }
+    snapshotLruAccounting() {
+        this.metrics.setCacheArtifactByteAccountingRef(this.lru.toArray().map(({ key, value }) => ({
+            artifactId: key,
+            totalContentBytes: value.totalContentBytes,
+            updatedAt: value.updatedAt
+        })));
     }
 }
 function remapJvmDescriptor(descriptor, classMap) {