@adhisang/minecraft-modding-mcp 3.1.0 → 3.2.0

package/dist/source-service.js

@@ -1,23 +1,24 @@
 import { createHash } from "node:crypto";
 import { existsSync } from "node:fs";
-import { readFile, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
+import { access, readFile, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, 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 { decompileBinaryJar } from "./decompiler/vineflower.js";
 import { resolveVineflowerJar } from "./vineflower-resolver.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";
@@ -26,6 +27,7 @@ import { SymbolsRepo } from "./storage/symbols-repo.js";
 import { RuntimeMetrics } from "./observability.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";
@@ -159,6 +161,7 @@ function clampLimit(limit, fallback, max) {
 }
 const MAX_REGEX_QUERY_LENGTH = 200;
 const MAX_REGEX_RESULT_LIMIT = 100;
+const TRACE_LIFECYCLE_MAX_CONCURRENCY = 3;
 function normalizePathStyle(path) {
     return path.replaceAll("\\", "/");
 }
@@ -177,6 +180,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) {
@@ -203,39 +230,17 @@ 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);
 }
-function resolveGradleUserHomePath() {
-    const configured = process.env.GRADLE_USER_HOME?.trim();
-    if (!configured) {
-        return resolvePath(homedir(), ".gradle");
+function looksLikeJvmMethodDescriptor(descriptor) {
+    const trimmed = descriptor?.trim();
+    if (!trimmed || !trimmed.startsWith("(")) {
+        return false;
     }
-    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];
+    const closing = trimmed.indexOf(")");
+    return closing > 0 && closing < trimmed.length - 1;
 }
 function looksLikeMinecraftSourceArtifact(path, hasMinecraftNamespace) {
     if (hasMinecraftNamespace) {
@@ -278,16 +283,19 @@ function scopeToJarType(scope) {
 }
 function parseQualifiedMethodSymbol(symbol) {
     const trimmed = symbol.trim();
-    const separator = trimmed.lastIndexOf(".");
-    if (separator <= 0 || separator >= trimmed.length - 1) {
+    const descriptorStart = trimmed.indexOf("(");
+    const qualifiedSymbol = descriptorStart >= 0 ? trimmed.slice(0, descriptorStart) : trimmed;
+    const inlineDescriptor = descriptorStart >= 0 ? trimmed.slice(descriptorStart).trim() : undefined;
+    const separator = qualifiedSymbol.lastIndexOf(".");
+    if (separator <= 0 || separator >= qualifiedSymbol.length - 1) {
         throw createError({
             code: ERROR_CODES.INVALID_INPUT,
             message: `symbol must be in the form "fully.qualified.Class.method".`,
             details: { symbol }
         });
     }
-    const className = trimmed.slice(0, separator);
-    const methodName = trimmed.slice(separator + 1);
+    const className = qualifiedSymbol.slice(0, separator);
+    const methodName = qualifiedSymbol.slice(separator + 1);
     if (!className ||
         !methodName ||
         className.includes("/") ||
@@ -299,7 +307,11 @@ function parseQualifiedMethodSymbol(symbol) {
             details: { symbol }
         });
     }
-    return { className, methodName };
+    return {
+        className,
+        methodName,
+        ...(inlineDescriptor ? { inlineDescriptor } : {})
+    };
 }
 function normalizeOptionalString(value) {
     if (value == null) {
@@ -345,6 +357,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";
@@ -381,6 +402,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";
@@ -768,7 +802,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
@@ -832,6 +866,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
@@ -931,9 +1330,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
@@ -948,6 +1349,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") &&
@@ -956,7 +1360,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
@@ -991,7 +1399,8 @@ export class SourceService {
                 mappingDecision = applyMappingPipeline({
                     requestedMapping: effectiveMapping,
                     target: { kind, value },
-                    resolved
+                    resolved,
+                    runtimeNamesUnobfuscated
                 });
             }
             catch (caughtError) {
@@ -1420,7 +1829,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();
@@ -1642,10 +2058,152 @@ 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 } = parseQualifiedMethodSymbol(input.symbol);
-        const descriptor = normalizeOptionalString(input.descriptor);
+        const { className: userClassName, methodName: userMethodName, inlineDescriptor } = parseQualifiedMethodSymbol(input.symbol);
+        const descriptor = normalizeOptionalString(input.descriptor)
+            ?? (looksLikeJvmMethodDescriptor(inlineDescriptor) ? normalizeOptionalString(inlineDescriptor) : undefined);
         const includeTimeline = input.includeTimeline ?? false;
         const includeSnapshots = input.includeSnapshots ?? false;
         const maxVersions = clampLimit(input.maxVersions, 120, 400);
@@ -1701,60 +2259,75 @@ export class SourceService {
             selectedVersions = selectedVersions.slice(selectedVersions.length - maxVersions);
             warnings.push(`Version scan truncated to ${maxVersions} entries. Effective fromVersion is now "${selectedVersions[0]}".`);
         }
-        const resolvedSymbolsByVersion = new Map();
-        const scanned = [];
-        for (const version of selectedVersions) {
+        const referenceVersion = selectedVersions[selectedVersions.length - 1];
+        await this.rejectLifecycleClassLikeInput({
+            symbol: input.symbol,
+            className: userClassName,
+            methodName: userMethodName,
+            mapping,
+            version: referenceVersion,
+            sourcePriority: input.sourcePriority
+        });
+        const scannedResults = await mapWithConcurrencyLimit(selectedVersions, TRACE_LIFECYCLE_MAX_CONCURRENCY, async (version) => {
+            const versionWarnings = [];
             try {
-                let resolvedSymbols = resolvedSymbolsByVersion.get(version);
-                if (!resolvedSymbols) {
-                    const [obfuscatedClassName, obfuscatedMethod] = await Promise.all([
-                        this.resolveToObfuscatedClassName(userClassName, version, mapping, input.sourcePriority, warnings),
-                        this.resolveToObfuscatedMemberName(userMethodName, userClassName, descriptor, "method", version, mapping, input.sourcePriority, warnings)
-                    ]);
-                    resolvedSymbols = {
-                        className: obfuscatedClassName,
-                        methodName: obfuscatedMethod.name,
-                        methodDescriptor: obfuscatedMethod.descriptor
-                    };
-                    resolvedSymbolsByVersion.set(version, resolvedSymbols);
-                }
-                const resolvedJar = await this.versionService.resolveVersionJar(version);
+                const [obfuscatedClassName, obfuscatedMethod, resolvedJar] = await Promise.all([
+                    this.resolveToObfuscatedClassName(userClassName, version, mapping, input.sourcePriority, versionWarnings),
+                    this.resolveToObfuscatedMemberName(userMethodName, userClassName, descriptor, "method", version, mapping, input.sourcePriority, versionWarnings),
+                    this.versionService.resolveVersionJar(version)
+                ]);
                 const signature = await this.explorerService.getSignature({
-                    fqn: resolvedSymbols.className,
+                    fqn: obfuscatedClassName,
                     jarPath: resolvedJar.jarPath,
                     access: "all",
                     includeSynthetic: true
                 });
-                const sameNameMethods = signature.methods.filter((method) => method.name === resolvedSymbols.methodName);
-                const matchesDescriptor = (resolvedSymbols.methodDescriptor ?? descriptor)
-                    ? sameNameMethods.some((method) => method.jvmDescriptor === (resolvedSymbols.methodDescriptor ?? descriptor))
+                const sameNameMethods = signature.methods.filter((method) => method.name === obfuscatedMethod.name);
+                const effectiveDescriptor = obfuscatedMethod.descriptor ?? descriptor;
+                const matchesDescriptor = effectiveDescriptor
+                    ? sameNameMethods.some((method) => method.jvmDescriptor === effectiveDescriptor)
                     : sameNameMethods.length > 0;
                 const reason = !matchesDescriptor && descriptor && sameNameMethods.length > 0 ? "descriptor-mismatch" : undefined;
-                scanned.push({
-                    version,
-                    exists: matchesDescriptor,
-                    reason,
-                    determinate: true
-                });
+                return {
+                    entry: {
+                        version,
+                        exists: matchesDescriptor,
+                        reason,
+                        determinate: true
+                    },
+                    warnings: versionWarnings
+                };
             }
             catch (caughtError) {
                 if (isAppError(caughtError) && caughtError.code === ERROR_CODES.CLASS_NOT_FOUND) {
-                    scanned.push({
+                    return {
+                        entry: {
+                            version,
+                            exists: false,
+                            reason: "class-not-found",
+                            determinate: true
+                        },
+                        warnings: versionWarnings
+                    };
+                }
+                versionWarnings.push(`Failed to evaluate ${version}: ${caughtError instanceof Error ? caughtError.message : String(caughtError)}`);
+                return {
+                    entry: {
                         version,
                         exists: false,
-                        reason: "class-not-found",
-                        determinate: true
-                    });
-                    continue;
-                }
-                scanned.push({
-                    version,
-                    exists: false,
-                    reason: "unresolved",
-                    determinate: false
-                });
-                warnings.push(`Failed to evaluate ${version}: ${caughtError instanceof Error ? caughtError.message : String(caughtError)}`);
+                        reason: "unresolved",
+                        determinate: false
+                    },
+                    warnings: versionWarnings
+                };
             }
+            finally {
+                this.releaseLifecycleMappingGraph(version, input.sourcePriority);
+            }
+        });
+        const scanned = scannedResults.map((result) => result.entry);
+        for (const result of scannedResults) {
+            warnings.push(...result.warnings);
         }
         const determinate = scanned.filter((entry) => entry.determinate);
         const present = determinate.filter((entry) => entry.exists);
@@ -2695,17 +3268,18 @@ export class SourceService {
                     path: this.resolveMixinInputPath(path, "path")
                 },
                 sourcePath: path
-            })), input);
+            })), input, []);
         }
         const resolvedInput = mode === "project"
-            ? this.createProjectValidateMixinConfigInput(input)
+            ? await this.createProjectValidateMixinConfigInput(input)
             : input;
-        const configSources = await this.resolveMixinConfigSources(resolvedInput);
+        const { sources: configSources, warnings: configWarnings } = await this.resolveMixinConfigSources(resolvedInput);
         if (configSources.length === 0) {
-            throw createError({
-                code: ERROR_CODES.INVALID_INPUT,
-                message: "Mixin config(s) contain no mixin class entries."
-            });
+            const emptyOutput = this.buildValidateMixinOutput(mode, []);
+            return this.applyValidateMixinOutputCompaction({
+                ...emptyOutput,
+                warnings: [...new Set([...emptyOutput.warnings, ...configWarnings])]
+            }, input);
         }
         return this.validateMixinMany(mode, configSources.map((entry) => ({
             source: {
@@ -2715,19 +3289,19 @@ export class SourceService {
                 configPath: entry.configPath
             },
             sourcePath: entry.sourcePath
-        })), resolvedInput);
+        })), 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,
@@ -2770,7 +3344,8 @@ export class SourceService {
                 name: input.className,
                 sourceMapping: input.sourceMapping,
                 targetMapping: input.targetMapping,
-                sourcePriority: input.sourcePriority
+                sourcePriority: input.sourcePriority,
+                projectPath: input.projectPath
             });
         }
         const cacheKey = [
@@ -2778,7 +3353,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) {
@@ -2790,7 +3366,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;
@@ -2971,6 +3548,7 @@ export class SourceService {
                         sourceMapping: requestedMapping,
                         targetMapping: signatureLookupMapping,
                         sourcePriority: currentSourcePriority,
+                        projectPath: input.projectPath,
                         batchCaches: input.batchCaches
                     });
                     if (mapped.resolved && mapped.resolvedSymbol) {
@@ -3004,9 +3582,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;
@@ -3245,9 +3823,13 @@ export class SourceService {
     }
     async resolveMixinConfigSources(input) {
         if (input.input.mode !== "config") {
-            return [];
+            return {
+                sources: [],
+                warnings: []
+            };
         }
         const results = [];
+        const warnings = [];
         for (const rawConfigPath of input.input.configPaths) {
             const resolvedConfigPath = this.resolveMixinInputPath(rawConfigPath, "configPath");
             let configJson;
@@ -3268,6 +3850,7 @@ export class SourceService {
                 ...(configJson.server ?? [])
             ];
             if (classNames.length === 0) {
+                warnings.push(`Mixin config "${resolvedConfigPath}" contains no mixin class entries.`);
                 continue;
             }
             const projectBase = input.projectPath
@@ -3278,11 +3861,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) {
@@ -3291,7 +3884,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;
                     }
@@ -3302,9 +3895,12 @@ export class SourceService {
                 });
             }
         }
-        return results;
+        return {
+            sources: results,
+            warnings
+        };
     }
-    async validateMixinMany(mode, entries, input) {
+    async validateMixinMany(mode, entries, input, additionalWarnings) {
         const results = [];
         const batchWarningMode = input.warningMode ?? "aggregated";
         const { input: _discardedInput, ...sharedInput } = input;
@@ -3331,7 +3927,13 @@ export class SourceService {
                 });
             }
         }
-        return this.applyValidateMixinOutputCompaction(this.buildValidateMixinOutput(mode, results), input);
+        const output = this.buildValidateMixinOutput(mode, results);
+        return this.applyValidateMixinOutputCompaction({
+            ...output,
+            warnings: additionalWarnings.length === 0
+                ? output.warnings
+                : [...new Set([...output.warnings, ...additionalWarnings])]
+        }, input);
     }
     applyValidateMixinOutputCompaction(output, input) {
         let nextOutput = output;
@@ -3473,7 +4075,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;
@@ -3485,7 +4086,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) {
@@ -3494,22 +4115,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 {
@@ -3518,23 +4140,156 @@ 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,
-                    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 = 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,
+                    classAccessFlags: sig.classAccessFlags,
+                    constructors,
+                    methods,
+                    fields
+                });
+            }
+            catch {
+                warnings.push(`Could not load signature for class "${lookupFqn}".`);
+            }
+        }
+        const result = validateParsedAccessTransformer(parsed, membersByClass, warnings, {
+            includeRuntimeEvidence: runtimeAware
+        });
+        if (provenance) {
+            result.provenance = provenance;
+        }
+        return result;
     }
     getRuntimeMetrics() {
         return this.metrics.snapshot();
@@ -4045,6 +4800,38 @@ export class SourceService {
             details
         });
     }
+    rejectLifecycleClassLikeInput(input) {
+        if (!looksLikeClassSegment(input.methodName)) {
+            return;
+        }
+        const classLikeSymbol = `${input.className}.${input.methodName}`;
+        throw createError({
+            code: ERROR_CODES.INVALID_INPUT,
+            message: `symbol must be in the form "fully.qualified.Class.method".`,
+            details: {
+                symbol: input.symbol,
+                classLikeSymbol,
+                nextAction: "Pass lifecycle input as Class.method and use the separate descriptor field for exact overload matching.",
+                suggestedCall: input.version
+                    ? {
+                        tool: "check-symbol-exists",
+                        params: {
+                            version: input.version,
+                            kind: "class",
+                            name: classLikeSymbol,
+                            sourceMapping: input.mapping
+                        }
+                    }
+                    : undefined
+            }
+        });
+    }
+    releaseLifecycleMappingGraph(version, sourcePriority) {
+        if ("releaseGraphCacheEntry" in this.mappingService &&
+            typeof this.mappingService.releaseGraphCacheEntry === "function") {
+            this.mappingService.releaseGraphCacheEntry(version, sourcePriority);
+        }
+    }
     async resolveToObfuscatedClassName(className, version, mapping, sourcePriority, warnings) {
         return this.resolveClassNameForLookup({
             className,
@@ -4106,21 +4893,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)
@@ -4133,22 +4921,98 @@ 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,
@@ -4158,10 +5022,17 @@ export class SourceService {
                     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
@@ -4189,13 +5060,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
@@ -4540,4 +5418,39 @@ export class SourceService {
         this.metrics.setCacheArtifactByteAccountingRef(this.cacheMetricsState.lru);
     }
 }
+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