@adhisang/minecraft-modding-mcp 3.1.1 → 4.0.0

package/dist/source-service.js

@@ -1,31 +1,37 @@
 import { createHash } from "node:crypto";
-import { existsSync } from "node:fs";
-import { readFile, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
-import { dirname, isAbsolute, resolve as resolvePath } from "node:path";
+import { 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 } from "./minecraft-explorer-service.js";
+import { MinecraftExplorerService, modifierPrefix, parseFieldType, parseMethodDescriptor } from "./minecraft-explorer-service.js";
 import { parseMixinSource } from "./mixin-parser.js";
 import { parseAccessWidener } from "./access-widener-parser.js";
-import { validateParsedMixin, refreshMixinValidationOutcome, validateParsedAccessWidener } from "./mixin-validator.js";
+import { parseAccessTransformer } from "./access-transformer-parser.js";
+import { validateParsedMixin, refreshMixinValidationOutcome, validateParsedAccessWidener, validateParsedAccessTransformer } 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";
 import { extractSymbolsFromSource } from "./symbols/symbol-extractor.js";
-import { iterateJavaEntriesAsUtf8, listJavaEntries } from "./source-jar-reader.js";
+import { detectFabricLikeInputNamespace, iterateJavaEntriesAsUtf8, listJavaEntries } from "./source-jar-reader.js";
 import { openDatabase } from "./storage/db.js";
 import { ArtifactsRepo } from "./storage/artifacts-repo.js";
 import { FilesRepo } from "./storage/files-repo.js";
 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";
 import { createSearchHitAccumulator, decodeSearchCursor, encodeSearchCursor } from "./search-hit-accumulator.js";
 import { WorkspaceMappingService } from "./workspace-mapping-service.js";
 import { VersionService, isUnobfuscatedVersion } from "./version-service.js";
@@ -146,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) {
@@ -178,6 +204,30 @@ function hasExactVersionToken(path, version) {
         ?? rememberCachedRegex(VERSION_TOKEN_REGEX_CACHE, normalizedVersion, new RegExp(`(^|[^0-9a-z])${escapeRegexLiteral(normalizedVersion)}([^0-9a-z]|$)`, "i"));
     return pattern.test(normalizedPath);
 }
+function inferMergedRuntimeNamespaceHint(path) {
+    const normalizedPath = normalizePathStyle(path).toLowerCase();
+    if (normalizedPath.includes("merged-intermediary-v2") ||
+        normalizedPath.includes("merged-intermediary")) {
+        return "intermediary";
+    }
+    if (normalizedPath.includes("minecraft-merged-mojang") ||
+        normalizedPath.includes("merged-mojang")) {
+        return "mojang";
+    }
+    if (normalizedPath.includes("merged-named")) {
+        return "named";
+    }
+    return undefined;
+}
+function runtimeJarNamespaceHintScore(hint) {
+    if (hint === "intermediary" || hint === "mojang") {
+        return 8_000;
+    }
+    if (hint === "named") {
+        return 1_000;
+    }
+    return 0;
+}
 function looksLikeDeobfuscatedClassName(value) {
     const trimmed = value.trim();
     if (!trimmed) {
@@ -204,17 +254,6 @@ function buildResolveArtifactParams(target, extra = {}) {
         ...extra
     };
 }
-function normalizeOptionalProjectPath(projectPath) {
-    if (!projectPath) {
-        return undefined;
-    }
-    const trimmed = projectPath.trim();
-    if (!trimmed) {
-        return undefined;
-    }
-    const normalized = normalizePathForHost(trimmed, undefined, "projectPath");
-    return isAbsolute(normalized) ? normalized : resolvePath(process.cwd(), normalized);
-}
 function looksLikeClassSegment(name) {
     const trimmed = name.trim();
     return /^[A-Z_$]/.test(trimmed);
@@ -227,29 +266,6 @@ function looksLikeJvmMethodDescriptor(descriptor) {
     const closing = trimmed.indexOf(")");
     return closing > 0 && closing < trimmed.length - 1;
 }
-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"));
-        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 = resolveGradleUserHomePath();
-    roots.add(resolvePath(homeGradle, "loom-cache"));
-    roots.add(resolvePath(homeGradle, "caches", "fabric-loom"));
-    return [...roots];
-}
 function looksLikeMinecraftSourceArtifact(path, hasMinecraftNamespace) {
     if (hasMinecraftNamespace) {
         return true;
@@ -328,27 +344,6 @@ function normalizeOptionalString(value) {
     const trimmed = value.trim();
     return trimmed ? trimmed : undefined;
 }
-async function mapWithConcurrencyLimit(items, limit, mapper) {
-    if (items.length === 0) {
-        return [];
-    }
-    const results = new Array(items.length);
-    let nextIndex = 0;
-    const workerCount = Math.max(1, Math.min(Math.trunc(limit), items.length));
-    await Promise.all(Array.from({ length: workerCount }, async () => {
-        while (true) {
-            // Safe in Node's single-threaded event loop because no await occurs between
-            // reading and incrementing nextIndex inside this synchronous dispatch section.
-            const currentIndex = nextIndex;
-            nextIndex += 1;
-            if (currentIndex >= items.length) {
-                return;
-            }
-            results[currentIndex] = await mapper(items[currentIndex], currentIndex);
-        }
-    }));
-    return results;
-}
 function normalizeStrictPositiveInt(value, field) {
     if (value == null) {
         return undefined;
@@ -386,6 +381,15 @@ const MIXIN_PROJECT_DISCOVERY_IGNORES = [
     "**/out/**",
     "**/node_modules/**"
 ];
+async function pathExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function normalizeMapping(mapping) {
     if (mapping == null) {
         return "obfuscated";
@@ -422,6 +426,19 @@ function normalizeAccessWidenerNamespace(namespace) {
     }
     return undefined;
 }
+function normalizeAccessTransformerNamespace(namespace) {
+    const normalized = namespace?.trim().toLowerCase();
+    if (!normalized) {
+        return undefined;
+    }
+    if (normalized === "srg" || normalized === "mojang" || normalized === "obfuscated") {
+        return normalized;
+    }
+    return undefined;
+}
+function isSourceMappingNamespace(namespace) {
+    return namespace === "obfuscated" || namespace === "mojang" || namespace === "intermediary" || namespace === "yarn";
+}
 function normalizeMemberAccess(access) {
     if (access == null) {
         return "public";
@@ -775,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;
@@ -809,7 +827,7 @@ export class SourceService {
             searchedPaths.push(root);
             let discovered = [];
             try {
-                discovered = fastGlob.sync("**/*sources.jar", {
+                discovered = await fastGlob.glob("**/*sources.jar", {
                     cwd: root,
                     absolute: true,
                     onlyFiles: true
@@ -873,6 +891,371 @@ export class SourceService {
             selectedHasMinecraftNamespace: selected?.hasMinecraftNamespace
         };
     }
+    async discoverAccessWidenerRuntimeCandidates(input) {
+        const normalizedProjectPath = normalizeOptionalProjectPath(input.projectPath);
+        const normalizedProjectPathLower = normalizedProjectPath
+            ? normalizePathStyle(normalizedProjectPath).toLowerCase()
+            : undefined;
+        const searchRoots = buildVersionSourceSearchRoots(normalizedProjectPath);
+        const searchedPaths = [];
+        const candidates = [];
+        const seen = new Set();
+        for (const root of searchRoots) {
+            searchedPaths.push(root);
+            let discovered = [];
+            try {
+                discovered = await fastGlob.glob(["**/*minecraft*.jar", "**/*merged*.jar"], {
+                    cwd: root,
+                    absolute: true,
+                    onlyFiles: true,
+                    ignore: ["**/*sources.jar", "**/node_modules/**", "**/.git/**", "**/build/**", "**/out/**"]
+                });
+            }
+            catch {
+                continue;
+            }
+            for (const candidatePath of discovered) {
+                const normalizedPath = normalizePathStyle(candidatePath);
+                if (seen.has(normalizedPath)) {
+                    continue;
+                }
+                seen.add(normalizedPath);
+                const lower = normalizedPath.toLowerCase();
+                if (!lower.includes("minecraft")) {
+                    continue;
+                }
+                const exactVersionMatch = hasExactVersionToken(normalizedPath, input.version);
+                const looksMerged = lower.includes("minecraft-merged") || lower.includes("/merged/") || lower.includes("-merged");
+                const namespaceHint = inferMergedRuntimeNamespaceHint(normalizedPath);
+                const appliedScope = looksMerged
+                    ? "merged"
+                    : input.requestedScope === "loader"
+                        ? "merged"
+                        : input.requestedScope;
+                const score = (exactVersionMatch ? 5_000 : 0) +
+                    (looksMerged ? 4_000 : 0) +
+                    runtimeJarNamespaceHintScore(namespaceHint) +
+                    (normalizedProjectPathLower && lower.startsWith(normalizedProjectPathLower) ? 2_000 : 0) +
+                    (lower.includes("loom-cache") || lower.includes("/caches/fabric-loom/") ? 500 : 0) +
+                    (lower.includes("minecraft-client") || lower.includes("client") ? 100 : 0);
+                candidates.push({
+                    jarPath: normalizedPath,
+                    score,
+                    appliedScope,
+                    origin: lower.includes("loom-cache") || lower.includes("/caches/fabric-loom/")
+                        ? "loom-cache"
+                        : "local-jar",
+                    namespaceHint
+                });
+            }
+        }
+        candidates.sort((left, right) => {
+            if (right.score !== left.score) {
+                return right.score - left.score;
+            }
+            return left.jarPath.localeCompare(right.jarPath);
+        });
+        return {
+            searchedPaths,
+            candidateArtifacts: candidates.slice(0, 20).map((candidate) => candidate.jarPath),
+            selected: candidates[0]
+        };
+    }
+    async discoverAccessTransformerRuntimeCandidates(input) {
+        const normalizedProjectPath = normalizeOptionalProjectPath(input.projectPath);
+        const normalizedProjectPathLower = normalizedProjectPath
+            ? normalizePathStyle(normalizedProjectPath).toLowerCase()
+            : undefined;
+        const searchRoots = buildLoaderRuntimeSearchRoots(normalizedProjectPath);
+        const searchedPaths = [];
+        const candidates = [];
+        const seen = new Set();
+        const globs = [
+            "**/*minecraft*.jar",
+            "**/*patched*.jar",
+            "**/*srg*.jar",
+            "**/*joined*.jar",
+            "**/*client-extra*.jar",
+            "**/*forge*.jar",
+            "**/*neoforge*.jar",
+            "**/*moddev*.jar",
+            "**/*neoform*.jar"
+        ];
+        for (const root of searchRoots) {
+            searchedPaths.push(root);
+            if (!(await pathExists(root))) {
+                continue;
+            }
+            let discovered = [];
+            try {
+                discovered = await fastGlob.glob(globs, {
+                    cwd: root,
+                    absolute: true,
+                    onlyFiles: true,
+                    ignore: ["**/*sources.jar", "**/node_modules/**", "**/.git/**", "**/out/**"]
+                });
+            }
+            catch {
+                continue;
+            }
+            for (const candidatePath of discovered) {
+                const normalizedPath = normalizePathStyle(candidatePath);
+                if (seen.has(normalizedPath)) {
+                    continue;
+                }
+                seen.add(normalizedPath);
+                const lower = normalizedPath.toLowerCase();
+                if (!hasExactVersionToken(normalizedPath, input.version)) {
+                    continue;
+                }
+                const looksMerged = lower.includes("merged");
+                const looksSrg = lower.includes("srg");
+                const looksForge = lower.includes("forge");
+                const looksNeoForge = lower.includes("neoforge") || lower.includes("moddev") || lower.includes("neoform");
+                const looksPatchedRuntime = lower.includes("patched") || lower.includes("client-extra") || lower.includes("joined");
+                const appliedScope = looksMerged
+                    ? "merged"
+                    : "loader";
+                if (input.atNamespace === "srg" && !looksSrg) {
+                    continue;
+                }
+                if (input.loader === "forge" && !looksForge && !looksSrg && !looksPatchedRuntime) {
+                    continue;
+                }
+                if (input.loader === "neoforge" && !looksNeoForge && !looksPatchedRuntime && !lower.includes("minecraft")) {
+                    continue;
+                }
+                const score = 10_000 +
+                    (normalizedProjectPathLower && lower.startsWith(normalizedProjectPathLower) ? 4_000 : 0) +
+                    (looksPatchedRuntime ? 3_000 : 0) +
+                    (looksSrg ? 2_500 : 0) +
+                    (input.loader === "forge" && looksForge ? 1_500 : 0) +
+                    (input.loader === "neoforge" && looksNeoForge ? 1_500 : 0) +
+                    (input.requestedScope === appliedScope ? 1_000 : 0) +
+                    (looksMerged ? -500 : 0);
+                candidates.push({
+                    jarPath: normalizedPath,
+                    score,
+                    appliedScope,
+                    origin: "local-jar"
+                });
+            }
+        }
+        candidates.sort((left, right) => {
+            if (right.score !== left.score) {
+                return right.score - left.score;
+            }
+            return left.jarPath.localeCompare(right.jarPath);
+        });
+        return {
+            searchedPaths,
+            candidateArtifacts: candidates.slice(0, 20).map((candidate) => candidate.jarPath),
+            selected: candidates[0]
+        };
+    }
+    async resolveAccessWidenerRuntimeArtifact(input) {
+        const normalizedProjectPath = normalizeOptionalProjectPath(input.projectPath);
+        let version = input.version;
+        if (input.preferProjectVersion && normalizedProjectPath) {
+            const detected = await this.workspaceMappingService.detectProjectMinecraftVersion(normalizedProjectPath);
+            version = detected ?? version;
+        }
+        const requestedScope = input.scope ?? (normalizedProjectPath ? "loader" : "vanilla");
+        if (requestedScope === "vanilla") {
+            const versionJar = await this.versionService.resolveVersionJar(version);
+            return {
+                version: versionJar.version,
+                jarPath: versionJar.jarPath,
+                requestedScope,
+                appliedScope: "vanilla",
+                requestedMapping: input.awNamespace,
+                mappingApplied: "obfuscated",
+                origin: "version-jar"
+            };
+        }
+        const discovery = await this.discoverAccessWidenerRuntimeCandidates({
+            version,
+            projectPath: normalizedProjectPath,
+            requestedScope
+        });
+        if (!discovery.selected) {
+            throw createError({
+                code: ERROR_CODES.CONTEXT_UNRESOLVED,
+                message: "Could not resolve a runtime jar for Access Widener validation.",
+                details: {
+                    version,
+                    requestedScope,
+                    projectPath: normalizedProjectPath,
+                    searchedPaths: discovery.searchedPaths,
+                    candidateArtifacts: discovery.candidateArtifacts,
+                    nextAction: "Provide projectPath for a Loom workspace with generated runtime jars, or run Gradle tasks that populate the Loom cache before retrying.",
+                    suggestedCall: {
+                        tool: "validate-access-widener",
+                        params: {
+                            version,
+                            scope: requestedScope,
+                            ...(normalizedProjectPath ? { projectPath: normalizedProjectPath } : {})
+                        }
+                    }
+                }
+            });
+        }
+        const appliedScope = discovery.selected.appliedScope;
+        const scopeFallback = requestedScope !== appliedScope
+            ? {
+                requested: requestedScope,
+                applied: appliedScope,
+                reason: requestedScope === "loader"
+                    ? "Fabric loader runtime validation currently reuses the merged runtime jar."
+                    : "Selected runtime jar matched a nearby merged artifact."
+            }
+            : undefined;
+        let detectedMapping;
+        const notes = [];
+        if (scopeFallback) {
+            notes.push(scopeFallback.reason);
+        }
+        if (isUnobfuscatedVersion(version)) {
+            detectedMapping = "obfuscated";
+        }
+        else if (discovery.selected.namespaceHint === "intermediary" ||
+            discovery.selected.namespaceHint === "mojang") {
+            detectedMapping = discovery.selected.namespaceHint;
+        }
+        else {
+            const detection = await detectFabricLikeInputNamespace(discovery.selected.jarPath);
+            detectedMapping = detection.fromNamespace;
+            if (detection.warnings.length > 0) {
+                notes.push(...detection.warnings);
+            }
+        }
+        return {
+            version,
+            jarPath: discovery.selected.jarPath,
+            requestedScope,
+            appliedScope,
+            requestedMapping: input.awNamespace,
+            mappingApplied: detectedMapping,
+            origin: discovery.selected.origin,
+            resolutionNotes: notes.length > 0 ? notes : undefined,
+            scopeFallback
+        };
+    }
+    async resolveAccessTransformerNamespace(input) {
+        const explicit = normalizeAccessTransformerNamespace(input.atNamespace);
+        if (explicit) {
+            return explicit;
+        }
+        const normalizedProjectPath = normalizeOptionalProjectPath(input.projectPath);
+        if (!normalizedProjectPath) {
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: "atNamespace is required when projectPath is not provided.",
+                details: {
+                    nextAction: "Pass atNamespace explicitly, or provide projectPath for a Forge/NeoForge workspace so the namespace can be inferred."
+                }
+            });
+        }
+        const loaderDetection = await this.workspaceMappingService.detectProjectLoader(normalizedProjectPath);
+        if (loaderDetection.resolved && loaderDetection.loader === "forge") {
+            return "srg";
+        }
+        if (loaderDetection.resolved && loaderDetection.loader === "neoforge") {
+            return "mojang";
+        }
+        throw createError({
+            code: ERROR_CODES.INVALID_INPUT,
+            message: "Could not infer atNamespace from the workspace.",
+            details: {
+                projectPath: normalizedProjectPath,
+                evidence: loaderDetection.evidence,
+                warnings: loaderDetection.warnings,
+                nextAction: "Pass atNamespace explicitly, or point projectPath at a Forge/NeoForge workspace."
+            }
+        });
+    }
+    async resolveAccessTransformerRuntimeArtifact(input) {
+        const normalizedProjectPath = normalizeOptionalProjectPath(input.projectPath);
+        let version = input.version;
+        if (input.preferProjectVersion && normalizedProjectPath) {
+            const detected = await this.workspaceMappingService.detectProjectMinecraftVersion(normalizedProjectPath);
+            version = detected ?? version;
+        }
+        const requestedScope = input.scope ?? (normalizedProjectPath ? "loader" : "vanilla");
+        if (requestedScope === "vanilla") {
+            if (input.atNamespace === "srg") {
+                throw createError({
+                    code: ERROR_CODES.INVALID_INPUT,
+                    message: "atNamespace=srg requires projectPath and scope=loader so a Forge runtime jar can be resolved."
+                });
+            }
+            const versionJar = await this.versionService.resolveVersionJar(version);
+            return {
+                version: versionJar.version,
+                jarPath: versionJar.jarPath,
+                requestedScope,
+                appliedScope: "vanilla",
+                requestedMapping: input.atNamespace,
+                mappingApplied: "obfuscated",
+                origin: "version-jar"
+            };
+        }
+        const loaderDetection = normalizedProjectPath
+            ? await this.workspaceMappingService.detectProjectLoader(normalizedProjectPath)
+            : { resolved: false, loader: undefined, evidence: [], warnings: [] };
+        const loader = loaderDetection.resolved ? loaderDetection.loader ?? "unknown" : "unknown";
+        const discovery = await this.discoverAccessTransformerRuntimeCandidates({
+            version,
+            projectPath: normalizedProjectPath,
+            requestedScope,
+            atNamespace: input.atNamespace,
+            loader
+        });
+        if (!discovery.selected) {
+            throw createError({
+                code: ERROR_CODES.CONTEXT_UNRESOLVED,
+                message: "Could not resolve a runtime jar for Access Transformer validation.",
+                details: {
+                    version,
+                    requestedScope,
+                    atNamespace: input.atNamespace,
+                    projectPath: normalizedProjectPath,
+                    searchedPaths: discovery.searchedPaths,
+                    candidateArtifacts: discovery.candidateArtifacts,
+                    loaderEvidence: loaderDetection.evidence,
+                    loaderWarnings: loaderDetection.warnings,
+                    nextAction: "Provide projectPath for a Forge/NeoForge workspace with generated runtime jars, or run the Gradle tasks that populate transformed runtime artifacts before retrying."
+                }
+            });
+        }
+        const selected = discovery.selected;
+        const selectedLower = selected.jarPath.toLowerCase();
+        const mappingApplied = input.atNamespace === "srg" || selectedLower.includes("srg")
+            ? "srg"
+            : loader === "neoforge" || selectedLower.includes("moddev") || selectedLower.includes("neoforge")
+                ? "mojang"
+                : "obfuscated";
+        const scopeFallback = requestedScope !== selected.appliedScope
+            ? {
+                requested: requestedScope,
+                applied: selected.appliedScope,
+                reason: selected.appliedScope === "merged"
+                    ? "Resolved a nearby merged runtime jar because no transformed loader artifact was available."
+                    : "Resolved the closest transformed runtime artifact for validation."
+            }
+            : undefined;
+        return {
+            version,
+            jarPath: selected.jarPath,
+            requestedScope,
+            appliedScope: selected.appliedScope,
+            requestedMapping: input.atNamespace,
+            mappingApplied,
+            origin: selected.origin,
+            resolutionNotes: scopeFallback ? [scopeFallback.reason] : undefined,
+            scopeFallback
+        };
+    }
     buildVersionSourceRecoveryCommand(projectPath) {
         const normalizedProjectPath = normalizeOptionalProjectPath(projectPath);
         const prefix = normalizedProjectPath
@@ -880,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"
@@ -972,9 +1440,11 @@ export class SourceService {
             let resolvedTarget = { kind, value };
             let resolvedVersion;
             let versionSourceDiscovery;
+            let runtimeNamesUnobfuscated = false;
             if (kind === "version") {
                 const versionJar = await this.versionService.resolveVersionJar(value);
                 resolvedVersion = versionJar.version;
+                runtimeNamesUnobfuscated = isUnobfuscatedVersion(resolvedVersion);
                 resolvedTarget = {
                     kind: "jar",
                     value: versionJar.jarPath
@@ -989,6 +1459,9 @@ export class SourceService {
                     // coordinate validity is validated by resolver, keep version undefined on parse failure.
                 }
             }
+            if (!runtimeNamesUnobfuscated && resolvedVersion && isUnobfuscatedVersion(resolvedVersion)) {
+                runtimeNamesUnobfuscated = true;
+            }
             // Unobfuscated versions (MC 26.1+) ship with deobfuscated runtime names; intermediary/yarn are not applicable.
             let effectiveMapping = mapping;
             if ((mapping === "intermediary" || mapping === "yarn") &&
@@ -997,7 +1470,11 @@ export class SourceService {
                 warnings.push(`Version ${resolvedVersion} is unobfuscated; ${mapping} mappings are not applicable. Using the obfuscated namespace label for the deobfuscated runtime names.`);
                 effectiveMapping = "obfuscated";
             }
-            if (kind === "version" && resolvedVersion && effectiveMapping === "mojang" && scope !== "vanilla") {
+            if (kind === "version" &&
+                resolvedVersion &&
+                effectiveMapping === "mojang" &&
+                !runtimeNamesUnobfuscated &&
+                scope !== "vanilla") {
                 versionSourceDiscovery = await this.discoverVersionSourceJar({
                     version: resolvedVersion,
                     projectPath: input.projectPath
@@ -1010,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", {
@@ -1032,7 +1528,9 @@ export class SourceService {
                 mappingDecision = applyMappingPipeline({
                     requestedMapping: effectiveMapping,
                     target: { kind, value },
-                    resolved
+                    resolved,
+                    runtimeNamesUnobfuscated,
+                    allowBinaryRemap: binaryRemapGate.allowBinaryRemap
                 });
             }
             catch (caughtError) {
@@ -1149,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;
@@ -1166,6 +1684,7 @@ export class SourceService {
             }
             return {
                 artifactId: resolved.artifactId,
+                artifactAlias,
                 origin: resolved.origin,
                 isDecompiled: resolved.isDecompiled,
                 resolvedSourceJarPath: resolved.sourceJarPath,
@@ -1210,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",
@@ -1226,8 +1745,82 @@ export class SourceService {
             }
             const intent = normalizeIntent(input.intent);
             const match = normalizeMatch(input.match);
-            if (match === "regex" && query.length > MAX_REGEX_QUERY_LENGTH) {
-                throw createError({
+            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,
                     message: `Regex query exceeds max length of ${MAX_REGEX_QUERY_LENGTH} characters.`,
                     details: {
@@ -1239,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,
@@ -1348,7 +1943,9 @@ export class SourceService {
                     sourceJarPath: artifact.sourceJarPath,
                     isDecompiled: artifact.isDecompiled,
                     qualityFlags: artifact.qualityFlags
-                })
+                }),
+                ...(translatedInfo ? { translatedQuery: translatedInfo } : {}),
+                ...(searchWarnings.length > 0 ? { warnings: searchWarnings } : {})
             };
         }
         finally {
@@ -1461,7 +2058,14 @@ export class SourceService {
         return this.mappingService.getClassApiMatrix(input);
     }
     async checkSymbolExists(input) {
-        return this.mappingService.checkSymbolExists(input);
+        const result = await this.mappingService.checkSymbolExists(input);
+        if (result.status !== "mapping_unavailable" ||
+            !isUnobfuscatedVersion(input.version) ||
+            (input.sourceMapping !== "mojang" && input.sourceMapping !== "obfuscated")) {
+            return result;
+        }
+        const runtimeFallback = await this.checkSymbolExistsInUnobfuscatedRuntime(input, result);
+        return runtimeFallback ?? result;
     }
     async resolveWorkspaceSymbol(input) {
         const projectPath = input.projectPath?.trim();
@@ -1645,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,
@@ -1683,6 +2291,147 @@ export class SourceService {
             warnings: [...warnings, ...mapped.warnings]
         };
     }
+    async checkSymbolExistsInUnobfuscatedRuntime(input, fallbackBase) {
+        const version = input.version.trim();
+        const name = input.name.trim();
+        const owner = input.owner?.trim();
+        if (!version || !name) {
+            return undefined;
+        }
+        if (input.kind === "class" && input.nameMode !== "fqcn" && !name.includes(".")) {
+            return {
+                ...fallbackBase,
+                warnings: [
+                    ...fallbackBase.warnings,
+                    `Version ${version} is unobfuscated, but short class name "${name}" could not be checked against runtime bytecode without a fully-qualified name.`
+                ]
+            };
+        }
+        const querySymbol = input.kind === "class"
+            ? {
+                kind: "class",
+                name,
+                symbol: name
+            }
+            : input.kind === "field"
+                ? {
+                    kind: "field",
+                    owner,
+                    name,
+                    symbol: `${owner}.${name}`
+                }
+                : {
+                    kind: "method",
+                    owner,
+                    name,
+                    descriptor: input.descriptor?.trim(),
+                    symbol: `${owner}.${name}${input.descriptor?.trim() ?? ""}`
+                };
+        const targetClass = input.kind === "class" ? name : owner;
+        if (!targetClass) {
+            return fallbackBase;
+        }
+        let jarPath;
+        try {
+            ({ jarPath } = await this.versionService.resolveVersionJar(version));
+        }
+        catch {
+            return undefined;
+        }
+        let signature;
+        try {
+            signature = await this.explorerService.getSignature({
+                fqn: targetClass,
+                jarPath,
+                access: "all"
+            });
+        }
+        catch {
+            return {
+                ...fallbackBase,
+                querySymbol,
+                warnings: [
+                    ...fallbackBase.warnings,
+                    `Version ${version} is unobfuscated; runtime bytecode lookup could not load class "${targetClass}".`
+                ]
+            };
+        }
+        const warnings = [
+            ...fallbackBase.warnings,
+            ...signature.warnings,
+            `Version ${version} is unobfuscated; validated symbol existence against runtime bytecode.`
+        ];
+        const buildResolved = (resolvedSymbol) => ({
+            ...fallbackBase,
+            querySymbol,
+            resolved: true,
+            status: "resolved",
+            resolvedSymbol,
+            candidates: resolvedSymbol
+                ? [{
+                        ...resolvedSymbol,
+                        matchKind: "exact",
+                        confidence: 1
+                    }]
+                : [],
+            candidateCount: resolvedSymbol ? 1 : 0,
+            warnings
+        });
+        const buildUnresolved = (status) => ({
+            ...fallbackBase,
+            querySymbol,
+            resolved: false,
+            status,
+            resolvedSymbol: undefined,
+            candidates: [],
+            candidateCount: 0,
+            warnings
+        });
+        if (input.kind === "class") {
+            return buildResolved({
+                kind: "class",
+                name,
+                symbol: name
+            });
+        }
+        if (input.kind === "field") {
+            const matched = signature.fields.filter((field) => field.name === name);
+            if (matched.length !== 1) {
+                return buildUnresolved(matched.length > 1 ? "ambiguous" : "not_found");
+            }
+            return buildResolved({
+                kind: "field",
+                owner,
+                name,
+                symbol: `${owner}.${name}`
+            });
+        }
+        const methodCandidates = signature.methods.filter((method) => method.name === name);
+        if (input.signatureMode === "name-only") {
+            if (methodCandidates.length !== 1) {
+                return buildUnresolved(methodCandidates.length > 1 ? "ambiguous" : "not_found");
+            }
+            return buildResolved({
+                kind: "method",
+                owner,
+                name,
+                descriptor: methodCandidates[0]?.jvmDescriptor,
+                symbol: `${owner}.${name}${methodCandidates[0]?.jvmDescriptor ?? ""}`
+            });
+        }
+        const descriptor = input.descriptor?.trim();
+        const matched = methodCandidates.filter((method) => method.jvmDescriptor === descriptor);
+        if (matched.length !== 1) {
+            return buildUnresolved(matched.length > 1 ? "ambiguous" : "not_found");
+        }
+        return buildResolved({
+            kind: "method",
+            owner,
+            name,
+            descriptor,
+            symbol: `${owner}.${name}${descriptor ?? ""}`
+        });
+    }
     async traceSymbolLifecycle(input) {
         const mapping = normalizeMapping(input.mapping);
         const { className: userClassName, methodName: userMethodName, inlineDescriptor } = parseQualifiedMethodSymbol(input.symbol);
@@ -2129,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(".");
@@ -2294,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;
@@ -2577,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;
@@ -2683,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: {
@@ -2699,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") {
@@ -2755,7 +3611,7 @@ export class SourceService {
             })), input, []);
         }
         const resolvedInput = mode === "project"
-            ? this.createProjectValidateMixinConfigInput(input)
+            ? await this.createProjectValidateMixinConfigInput(input)
             : input;
         const { sources: configSources, warnings: configWarnings } = await this.resolveMixinConfigSources(resolvedInput);
         if (configSources.length === 0) {
@@ -2775,22 +3631,23 @@ export class SourceService {
             sourcePath: entry.sourcePath
         })), resolvedInput, configWarnings);
     }
-    createProjectValidateMixinConfigInput(input) {
+    async createProjectValidateMixinConfigInput(input) {
         if (input.input.mode !== "project") {
             return input;
         }
         const resolvedProjectPath = this.resolveMixinInputPath(input.input.path, "path");
-        const configPaths = fastGlob.sync(["**/*.mixins.json"], {
+        const configPaths = (await fastGlob.glob(["**/*.mixins.json"], {
             cwd: resolvedProjectPath,
             absolute: true,
             onlyFiles: true,
             ignore: [...MIXIN_PROJECT_DISCOVERY_IGNORES]
-        }).sort((left, right) => left.localeCompare(right));
+        })).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: {
+                    failedStage: "input-validation",
                     nextAction: "Use input.mode='config' with explicit configPaths[], or point input.path at the workspace root that contains *.mixins.json files."
                 }
             });
@@ -2828,7 +3685,8 @@ export class SourceService {
                 name: input.className,
                 sourceMapping: input.sourceMapping,
                 targetMapping: input.targetMapping,
-                sourcePriority: input.sourcePriority
+                sourcePriority: input.sourcePriority,
+                projectPath: input.projectPath
             });
         }
         const cacheKey = [
@@ -2836,7 +3694,8 @@ export class SourceService {
             input.className,
             input.sourceMapping,
             input.targetMapping,
-            input.sourcePriority
+            input.sourcePriority,
+            input.projectPath ?? ""
         ].join("\0");
         const cached = cache.get(cacheKey);
         if (cached) {
@@ -2848,7 +3707,8 @@ export class SourceService {
             name: input.className,
             sourceMapping: input.sourceMapping,
             targetMapping: input.targetMapping,
-            sourcePriority: input.sourcePriority
+            sourcePriority: input.sourcePriority,
+            projectPath: input.projectPath
         }).catch((error) => {
             cache.delete(cacheKey);
             throw error;
@@ -2857,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)
@@ -2968,6 +3862,7 @@ export class SourceService {
             };
         }
         // Health check: probe mapping infrastructure
+        onStage("mapping-health");
         let healthReport;
         try {
             const health = await this.mappingService.checkMappingHealth({
@@ -2989,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();
@@ -3029,6 +3938,7 @@ export class SourceService {
                         sourceMapping: requestedMapping,
                         targetMapping: signatureLookupMapping,
                         sourcePriority: currentSourcePriority,
+                        projectPath: input.projectPath,
                         batchCaches: input.batchCaches
                     });
                     if (mapped.resolved && mapped.resolvedSymbol) {
@@ -3062,9 +3972,9 @@ export class SourceService {
                 if (requestedMapping !== signatureLookupMapping) {
                     try {
                         const [ctorResult, methodResult, fieldResult] = await Promise.all([
-                            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)
+                            this.remapSignatureMembers(sig.constructors, "method", version, signatureLookupMapping, requestedMapping, currentSourcePriority, warnings, input.projectPath),
+                            this.remapSignatureMembers(sig.methods, "method", version, signatureLookupMapping, requestedMapping, currentSourcePriority, warnings, input.projectPath),
+                            this.remapSignatureMembers(sig.fields, "field", version, signatureLookupMapping, requestedMapping, currentSourcePriority, warnings, input.projectPath)
                         ]);
                         constructors = ctorResult.members;
                         methods = methodResult.members;
@@ -3252,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;
@@ -3263,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 {
@@ -3286,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)}`);
@@ -3320,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 ?? "";
@@ -3341,11 +4265,21 @@ export class SourceService {
                 sourceRootCandidates = input.sourceRoots;
             }
             else {
-                const detected = COMMON_SOURCE_ROOTS.filter((candidateRoot) => classNames.some((className) => {
-                    const fqcn = pkg ? `${pkg}.${className}` : className;
-                    const relative = fqcn.replace(/\./g, "/") + ".java";
-                    return existsSync(resolvePath(projectBase, candidateRoot, relative));
-                }));
+                const detected = [];
+                for (const candidateRoot of COMMON_SOURCE_ROOTS) {
+                    let foundInRoot = false;
+                    for (const className of classNames) {
+                        const fqcn = pkg ? `${pkg}.${className}` : className;
+                        const relative = fqcn.replace(/\./g, "/") + ".java";
+                        if (await pathExists(resolvePath(projectBase, candidateRoot, relative))) {
+                            foundInRoot = true;
+                            break;
+                        }
+                    }
+                    if (foundInRoot) {
+                        detected.push(candidateRoot);
+                    }
+                }
                 sourceRootCandidates = detected.length > 0 ? detected : ["src/main/java"];
             }
             for (const cls of classNames) {
@@ -3354,7 +4288,7 @@ export class SourceService {
                 let sourcePath = resolvePath(projectBase, sourceRootCandidates[0], relativePath);
                 for (const root of sourceRootCandidates) {
                     const candidate = resolvePath(projectBase, root, relativePath);
-                    if (existsSync(candidate)) {
+                    if (await pathExists(candidate)) {
                         sourcePath = candidate;
                         break;
                     }
@@ -3545,7 +4479,6 @@ export class SourceService {
             throw createError({ code: ERROR_CODES.INVALID_INPUT, message: "content must be non-empty." });
         }
         const warnings = [];
-        const { jarPath } = await this.versionService.resolveVersionJar(version);
         const parsed = parseAccessWidener(content);
         const headerNamespaceRaw = normalizeOptionalString(parsed.namespace);
         const overrideMapping = input.mapping ? normalizeMapping(input.mapping) : undefined;
@@ -3557,7 +4490,27 @@ export class SourceService {
         if (overrideMapping && headerNamespace && overrideMapping !== headerNamespace) {
             warnings.push(`Using mapping override "${overrideMapping}" instead of header namespace "${headerNamespaceRaw}".`);
         }
-        const needsMapping = awNamespace !== "obfuscated";
+        const runtimeAware = input.projectPath != null || input.scope != null || input.preferProjectVersion === true;
+        let resolvedVersion = version;
+        let jarPath;
+        let lookupMapping = "obfuscated";
+        let provenance;
+        if (runtimeAware) {
+            provenance = await this.resolveAccessWidenerRuntimeArtifact({
+                version,
+                awNamespace,
+                projectPath: input.projectPath,
+                scope: input.scope,
+                preferProjectVersion: input.preferProjectVersion
+            });
+            resolvedVersion = provenance.version;
+            jarPath = provenance.jarPath;
+            lookupMapping = provenance.mappingApplied;
+        }
+        else {
+            ({ jarPath } = await this.versionService.resolveVersionJar(version));
+        }
+        const needsLookupMapping = awNamespace !== lookupMapping;
         // Collect unique class FQNs from entries
         const classFqns = new Set();
         for (const entry of parsed.entries) {
@@ -3566,22 +4519,23 @@ export class SourceService {
         }
         const membersByClass = new Map();
         for (const fqn of classFqns) {
-            let obfuscatedFqn = fqn;
-            if (needsMapping) {
+            let lookupFqn = fqn;
+            if (needsLookupMapping) {
                 try {
                     const mapped = await this.mappingService.findMapping({
-                        version,
+                        version: resolvedVersion,
                         kind: "class",
                         name: fqn,
                         sourceMapping: awNamespace,
-                        targetMapping: "obfuscated",
-                        sourcePriority: input.sourcePriority
+                        targetMapping: lookupMapping,
+                        sourcePriority: input.sourcePriority,
+                        projectPath: input.projectPath
                     });
                     if (mapped.resolved && mapped.resolvedSymbol) {
-                        obfuscatedFqn = mapped.resolvedSymbol.name;
+                        lookupFqn = mapped.resolvedSymbol.name;
                     }
                     else {
-                        warnings.push(`Could not map class "${fqn}" from ${awNamespace} to obfuscated.`);
+                        warnings.push(`Could not map class "${fqn}" from ${awNamespace} to ${lookupMapping}.`);
                     }
                 }
                 catch {
@@ -3590,25 +4544,163 @@ export class SourceService {
             }
             try {
                 const sig = await this.explorerService.getSignature({
-                    fqn: obfuscatedFqn,
+                    fqn: lookupFqn,
+                    jarPath,
+                    access: "all"
+                });
+                warnings.push(...sig.warnings);
+                let constructors = sig.constructors;
+                let methods = sig.methods;
+                let fields = sig.fields;
+                if (needsLookupMapping) {
+                    const [ctorResult, methodResult, fieldResult] = await Promise.all([
+                        this.remapSignatureMembers(sig.constructors, "method", resolvedVersion, lookupMapping, awNamespace, input.sourcePriority, warnings, input.projectPath),
+                        this.remapSignatureMembers(sig.methods, "method", resolvedVersion, lookupMapping, awNamespace, input.sourcePriority, warnings, input.projectPath),
+                        this.remapSignatureMembers(sig.fields, "field", resolvedVersion, lookupMapping, awNamespace, input.sourcePriority, warnings, input.projectPath)
+                    ]);
+                    constructors = ctorResult.members;
+                    methods = methodResult.members;
+                    fields = fieldResult.members;
+                }
+                membersByClass.set(fqn, {
+                    className: fqn,
+                    classAccessFlags: sig.classAccessFlags,
+                    constructors,
+                    methods,
+                    fields
+                });
+            }
+            catch {
+                warnings.push(`Could not load signature for class "${lookupFqn}".`);
+            }
+        }
+        const result = validateParsedAccessWidener(parsed, membersByClass, warnings, {
+            includeRuntimeEvidence: runtimeAware
+        });
+        if (provenance) {
+            result.provenance = provenance;
+        }
+        return result;
+    }
+    async validateAccessTransformer(input) {
+        const version = input.version.trim();
+        if (!version) {
+            throw createError({ code: ERROR_CODES.INVALID_INPUT, message: "version must be non-empty." });
+        }
+        const content = input.content;
+        if (!content.trim()) {
+            throw createError({ code: ERROR_CODES.INVALID_INPUT, message: "content must be non-empty." });
+        }
+        const warnings = [];
+        const parsed = parseAccessTransformer(content);
+        const atNamespace = await this.resolveAccessTransformerNamespace({
+            atNamespace: input.atNamespace,
+            projectPath: input.projectPath
+        });
+        const runtimeAware = input.projectPath != null || input.scope != null || input.preferProjectVersion === true;
+        let resolvedVersion = version;
+        let jarPath;
+        let lookupMapping = "obfuscated";
+        let provenance;
+        if (runtimeAware) {
+            provenance = await this.resolveAccessTransformerRuntimeArtifact({
+                version,
+                atNamespace,
+                projectPath: input.projectPath,
+                scope: input.scope,
+                preferProjectVersion: input.preferProjectVersion
+            });
+            resolvedVersion = provenance.version;
+            jarPath = provenance.jarPath;
+            lookupMapping = provenance.mappingApplied;
+        }
+        else {
+            if (atNamespace === "srg") {
+                throw createError({
+                    code: ERROR_CODES.INVALID_INPUT,
+                    message: "atNamespace=srg requires projectPath and scope=loader so a Forge runtime jar can be resolved."
+                });
+            }
+            ({ jarPath } = await this.versionService.resolveVersionJar(version));
+        }
+        const needsLookupMapping = atNamespace !== lookupMapping;
+        const classFqns = new Set(parsed.entries.map((entry) => entry.owner));
+        const membersByClass = new Map();
+        for (const fqn of classFqns) {
+            let lookupFqn = fqn;
+            if (needsLookupMapping) {
+                if (!isSourceMappingNamespace(atNamespace) || !isSourceMappingNamespace(lookupMapping)) {
+                    warnings.push(`Could not map class "${fqn}" from ${atNamespace} to ${lookupMapping}.`);
+                }
+                else {
+                    try {
+                        const mapped = await this.mappingService.findMapping({
+                            version: resolvedVersion,
+                            kind: "class",
+                            name: fqn,
+                            sourceMapping: atNamespace,
+                            targetMapping: lookupMapping,
+                            sourcePriority: input.sourcePriority,
+                            projectPath: input.projectPath
+                        });
+                        if (mapped.resolved && mapped.resolvedSymbol) {
+                            lookupFqn = mapped.resolvedSymbol.name;
+                        }
+                        else {
+                            warnings.push(`Could not map class "${fqn}" from ${atNamespace} to ${lookupMapping}.`);
+                        }
+                    }
+                    catch {
+                        warnings.push(`Mapping lookup failed for class "${fqn}".`);
+                    }
+                }
+            }
+            try {
+                const sig = await this.explorerService.getSignature({
+                    fqn: lookupFqn,
                     jarPath,
                     access: "all"
                 });
                 warnings.push(...sig.warnings);
+                let constructors = sig.constructors;
+                let methods = sig.methods;
+                let fields = sig.fields;
+                if (needsLookupMapping && isSourceMappingNamespace(atNamespace) && isSourceMappingNamespace(lookupMapping)) {
+                    const [ctorResult, methodResult, fieldResult] = await Promise.all([
+                        this.remapSignatureMembers(sig.constructors, "method", resolvedVersion, lookupMapping, atNamespace, input.sourcePriority, warnings, input.projectPath),
+                        this.remapSignatureMembers(sig.methods, "method", resolvedVersion, lookupMapping, atNamespace, input.sourcePriority, warnings, input.projectPath),
+                        this.remapSignatureMembers(sig.fields, "field", resolvedVersion, lookupMapping, atNamespace, input.sourcePriority, warnings, input.projectPath)
+                    ]);
+                    constructors = ctorResult.members;
+                    methods = methodResult.members;
+                    fields = fieldResult.members;
+                }
                 membersByClass.set(fqn, {
                     className: fqn,
-                    constructors: sig.constructors,
-                    methods: sig.methods,
-                    fields: sig.fields
+                    classAccessFlags: sig.classAccessFlags,
+                    constructors,
+                    methods,
+                    fields
                 });
             }
             catch {
-                warnings.push(`Could not load signature for class "${obfuscatedFqn}".`);
+                warnings.push(`Could not load signature for class "${lookupFqn}".`);
             }
         }
-        return validateParsedAccessWidener(parsed, membersByClass, warnings);
+        const result = validateParsedAccessTransformer(parsed, membersByClass, warnings, {
+            includeRuntimeEvidence: runtimeAware
+        });
+        if (provenance) {
+            result.provenance = provenance;
+        }
+        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) {
@@ -3936,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);
@@ -4188,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
@@ -4200,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) {
@@ -4210,21 +5448,22 @@ export class SourceService {
             descriptor: kind === "method" ? descriptor : undefined
         };
     }
-    async remapSignatureMembers(members, kind, version, sourceMapping, targetMapping, sourcePriority, warnings) {
+    async remapSignatureMembers(members, kind, version, sourceMapping, targetMapping, sourcePriority, warnings, projectPath) {
         const failedNames = new Set();
         if (sourceMapping === targetMapping) {
             return { members, failedNames };
         }
         // Build deduplicated lookup tables for member names and owner FQNs
         const memberKeyToRemapped = new Map();
+        const memberDescriptorRemapped = new Map();
         const ownerToRemapped = new Map();
         for (const member of members) {
             const memberKey = `${member.ownerFqn}\0${member.name}\0${member.jvmDescriptor}`;
             if (!memberKeyToRemapped.has(memberKey)) {
-                memberKeyToRemapped.set(memberKey, member.name); // default = obfuscated name
+                memberKeyToRemapped.set(memberKey, member.name); // default = source name
             }
             if (!ownerToRemapped.has(member.ownerFqn)) {
-                ownerToRemapped.set(member.ownerFqn, member.ownerFqn); // default = obfuscated FQN
+                ownerToRemapped.set(member.ownerFqn, member.ownerFqn); // default = source FQN
             }
         }
         // Phase 1: Remap owner FQNs first (needed for member disambiguation)
@@ -4237,35 +5476,122 @@ export class SourceService {
                     name: obfuscatedFqn,
                     sourceMapping,
                     targetMapping,
-                    sourcePriority
+                    sourcePriority,
+                    projectPath
                 });
                 if (mapped.resolved && mapped.resolvedSymbol) {
                     ownerToRemapped.set(obfuscatedFqn, mapped.resolvedSymbol.name);
                 }
             }
             catch {
-                // keep obfuscated FQN as fallback
+                // keep source FQN as fallback
             }
         }));
-        // Phase 2: Remap member names using resolved owners for disambiguation
+        // Phase 1.5: Collect class references from descriptors and remap them
+        const descriptorClassRefs = new Set();
+        for (const member of members) {
+            for (const match of member.jvmDescriptor.matchAll(/L([^;]+);/g)) {
+                const dotFqn = match[1].replace(/\//g, ".");
+                if (!ownerToRemapped.has(dotFqn)) {
+                    descriptorClassRefs.add(dotFqn);
+                }
+            }
+        }
+        if (descriptorClassRefs.size > 0) {
+            const refs = [...descriptorClassRefs];
+            for (const ref of refs) {
+                ownerToRemapped.set(ref, ref); // default = source name
+            }
+            await Promise.all(refs.map(async (dotFqn) => {
+                try {
+                    const mapped = await this.mappingService.findMapping({
+                        version,
+                        kind: "class",
+                        name: dotFqn,
+                        sourceMapping,
+                        targetMapping,
+                        sourcePriority,
+                        projectPath
+                    });
+                    if (mapped.resolved && mapped.resolvedSymbol) {
+                        ownerToRemapped.set(dotFqn, mapped.resolvedSymbol.name);
+                    }
+                }
+                catch {
+                    // keep source name as fallback
+                }
+            }));
+        }
+        // Build a class map for descriptor remapping (dot-FQN → dot-FQN)
+        const classMap = new Map();
+        for (const [src, tgt] of ownerToRemapped) {
+            if (src !== tgt) {
+                classMap.set(src, tgt);
+            }
+        }
+        // Phase 2: Remap member names (and descriptors for methods) using resolved owners
+        const canResolveMethodExactly = kind === "method" &&
+            "resolveMethodMappingExact" in this.mappingService &&
+            typeof this.mappingService.resolveMethodMappingExact === "function";
         const memberEntries = [...memberKeyToRemapped.entries()];
-        await Promise.all(memberEntries.map(async ([key, _obfuscatedName]) => {
+        await Promise.all(memberEntries.map(async ([key, _sourceName]) => {
             const [ownerFqn, name, descriptor] = key.split("\0");
             try {
                 const targetOwner = ownerToRemapped.get(ownerFqn) ?? ownerFqn;
+                // For methods with descriptors, try exact resolution first
+                if (canResolveMethodExactly && descriptor) {
+                    try {
+                        const exactResult = await this.mappingService.resolveMethodMappingExact({
+                            version,
+                            owner: ownerFqn,
+                            name: name,
+                            descriptor,
+                            sourceMapping,
+                            targetMapping,
+                            sourcePriority,
+                            projectPath
+                        });
+                        if (exactResult.resolved && exactResult.resolvedSymbol) {
+                            memberKeyToRemapped.set(key, exactResult.resolvedSymbol.name);
+                            if (exactResult.resolvedSymbol.descriptor) {
+                                memberDescriptorRemapped.set(key, exactResult.resolvedSymbol.descriptor);
+                            }
+                            return; // exact resolution succeeded
+                        }
+                        // Fall through to findMapping with descriptorHint
+                    }
+                    catch (exactError) {
+                        warnings.push(`Exact method resolution failed for "${name}" (falling back to name-based lookup): ${exactError instanceof Error ? exactError.message : String(exactError)}`);
+                    }
+                }
+                // Fallback: findMapping with descriptorHint for overload disambiguation
+                const remappedDescriptorHint = kind === "method" && descriptor
+                    ? remapJvmDescriptor(descriptor, classMap)
+                    : undefined;
                 const mapped = await this.mappingService.findMapping({
                     version,
                     kind,
                     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,
-                    disambiguation: { ownerHint: targetOwner }
+                    projectPath,
+                    disambiguation: {
+                        ownerHint: targetOwner,
+                        descriptorHint: remappedDescriptorHint
+                    }
                 });
                 if (mapped.resolved && mapped.resolvedSymbol) {
                     memberKeyToRemapped.set(key, mapped.resolvedSymbol.name);
+                    if (kind === "method" && mapped.resolvedSymbol.descriptor) {
+                        memberDescriptorRemapped.set(key, mapped.resolvedSymbol.descriptor);
+                    }
                 }
                 else if (mapped.status === "ambiguous" && mapped.candidates && mapped.candidates.length > 0) {
                     // Disambiguate: filter by target owner and pick the best candidate
@@ -4293,13 +5619,20 @@ export class SourceService {
                 failedNames.add(name);
             }
         }));
+        const isField = kind === "field";
         return {
             members: members.map((member) => {
                 const memberKey = `${member.ownerFqn}\0${member.name}\0${member.jvmDescriptor}`;
+                const remappedName = memberKeyToRemapped.get(memberKey) ?? member.name;
+                const remappedOwner = ownerToRemapped.get(member.ownerFqn) ?? member.ownerFqn;
+                const remappedDescriptor = memberDescriptorRemapped.get(memberKey)
+                    ?? remapJvmDescriptor(member.jvmDescriptor, classMap);
                 return {
                     ...member,
-                    name: memberKeyToRemapped.get(memberKey) ?? member.name,
-                    ownerFqn: ownerToRemapped.get(member.ownerFqn) ?? member.ownerFqn
+                    name: remappedName,
+                    ownerFqn: remappedOwner,
+                    jvmDescriptor: remappedDescriptor,
+                    javaSignature: rebuildJavaSignature({ name: remappedName, ownerFqn: remappedOwner, accessFlags: member.accessFlags }, remappedDescriptor, isField)
                 };
             }),
             failedNames
@@ -4326,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,
@@ -4348,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,
@@ -4399,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,
@@ -4504,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);
@@ -4519,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)) {
@@ -4534,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) {
@@ -4548,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();
@@ -4566,82 +6137,129 @@ 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) {
-            this.refreshCacheMetrics();
-            return;
-        }
-        const [existing] = this.cacheMetricsState.lru.splice(existingIndex, 1);
-        if (!existing) {
+        const entry = this.lru.touch(artifactId);
+        if (!entry) {
             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) {
+    if (classMap.size === 0) {
+        return descriptor;
+    }
+    return descriptor.replace(/L([^;]+);/g, (match, ref) => {
+        const dotFqn = ref.replace(/\//g, ".");
+        const remapped = classMap.get(dotFqn);
+        return remapped ? `L${remapped.replace(/\./g, "/")};` : match;
+    });
+}
+function rebuildJavaSignature(member, remappedDescriptor, isField) {
+    const modifiers = modifierPrefix(member.accessFlags, isField ? "field" : "method");
+    const prefix = modifiers ? `${modifiers} ` : "";
+    if (isField) {
+        try {
+            const { type } = parseFieldType(remappedDescriptor, 0, { allowVoid: false });
+            return `${prefix}${type} ${member.name}`.trim();
+        }
+        catch {
+            return `${prefix}${member.name}`.trim();
+        }
+    }
+    try {
+        const { args, returnType } = parseMethodDescriptor(remappedDescriptor);
+        const argStr = args.join(", ");
+        if (member.name === "<init>") {
+            const ownerSimple = member.ownerFqn.split(".").pop();
+            return `${prefix}${ownerSimple}(${argStr})`.trim();
+        }
+        return `${prefix}${returnType} ${member.name}(${argStr})`.trim();
+    }
+    catch {
+        return `${prefix}${member.name}`.trim();
     }
 }
 //# sourceMappingURL=source-service.js.map