@adhisang/minecraft-modding-mcp 3.1.1 → 4.0.0

package/dist/mapping-service.js

@@ -3,8 +3,9 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import fastGlob from "fast-glob";
 import { createError, ERROR_CODES } from "./errors.js";
+import { buildVersionSourceSearchRoots, normalizeOptionalProjectPath } from "./gradle-paths.js";
 import { defaultDownloadPath, downloadToCache } from "./repo-downloader.js";
-import { listJarEntries, readJarEntryAsUtf8 } from "./source-jar-reader.js";
+import { collectMatchedJarEntriesAsUtf8 } from "./source-jar-reader.js";
 import { VersionService, isUnobfuscatedVersion } from "./version-service.js";
 const SUPPORTED_MAPPINGS = new Set([
     "obfuscated",
@@ -19,6 +20,7 @@ const MATCH_RANK = {
 };
 const DESCRIPTOR_FALLBACK_CONFIDENCE = 0.85;
 const MAX_CANDIDATES = 200;
+const GLOB_SPECIAL_CHARS = /[\\!*+?()[\]{}@|]/g;
 function createDirectionIndex() {
     return {
         exact: new Map(),
@@ -706,15 +708,93 @@ function normalizeMemberName(name) {
     }
     return normalized;
 }
+/**
+ * Validate a JVM method descriptor such as `(I)V`, `()Lfoo/Bar;`, `(Lfoo/Bar;[I)V`.
+ * Rejects empty strings, missing/mis-positioned parens, empty return type, and invalid base
+ * type tokens so "(" or "()" style half-descriptors surface as ERR_INVALID_INPUT instead of
+ * being silently accepted.
+ */
 function normalizeMethodDescriptor(descriptor) {
     const normalized = descriptor?.trim() ?? "";
-    if (!normalized || !normalized.startsWith("(") || !normalized.includes(")")) {
+    if (!normalized) {
+        throw invalidInputError("descriptor must be a valid JVM descriptor when kind=method.", {
+            descriptor
+        });
+    }
+    if (!isValidMethodDescriptor(normalized)) {
         throw invalidInputError("descriptor must be a valid JVM descriptor when kind=method.", {
             descriptor
         });
     }
     return normalized;
 }
+function isValidMethodDescriptor(descriptor) {
+    if (!descriptor.startsWith("("))
+        return false;
+    const closingIndex = descriptor.indexOf(")");
+    if (closingIndex < 0)
+        return false;
+    const argsSection = descriptor.slice(1, closingIndex);
+    const returnSection = descriptor.slice(closingIndex + 1);
+    if (returnSection.length === 0)
+        return false;
+    let cursor = 0;
+    while (cursor < argsSection.length) {
+        const next = consumeFieldType(argsSection, cursor, /*allowVoid*/ false);
+        if (next < 0)
+            return false;
+        cursor = next;
+    }
+    const returnEnd = consumeFieldType(returnSection, 0, /*allowVoid*/ true);
+    return returnEnd === returnSection.length;
+}
+/**
+ * JVM specification §4.3.2: "An array type descriptor is valid only if it represents a type
+ * with 255 or fewer dimensions." Matches the `multianewarray` / field-signature limit.
+ */
+const JVM_MAX_ARRAY_DIMENSIONS = 255;
+function consumeFieldType(descriptor, position, allowVoid) {
+    // Arrays are handled iteratively so pathological inputs such as `(` + "[".repeat(20000) + `I)V`
+    // cannot blow the call stack. After consuming every leading `[`, only the element type token
+    // is dispatched through the switch below. Dimensions above the JVM limit are rejected rather
+    // than merely accepted as "syntactically valid but semantically absurd" — clients must not be
+    // able to push a 20000-dimension descriptor through cache-key construction.
+    let cursor = position;
+    let arrayDimensions = 0;
+    while (cursor < descriptor.length && descriptor[cursor] === "[") {
+        cursor += 1;
+        arrayDimensions += 1;
+        if (arrayDimensions > JVM_MAX_ARRAY_DIMENSIONS)
+            return -1;
+    }
+    if (cursor >= descriptor.length)
+        return -1;
+    // Void is only valid at the outermost position — inside an array element it is illegal.
+    const elementAllowsVoid = cursor === position && allowVoid;
+    const token = descriptor[cursor];
+    switch (token) {
+        case "B":
+        case "C":
+        case "D":
+        case "F":
+        case "I":
+        case "J":
+        case "S":
+        case "Z":
+            return cursor + 1;
+        case "V":
+            return elementAllowsVoid ? cursor + 1 : -1;
+        case "L": {
+            const end = descriptor.indexOf(";", cursor);
+            // Reject empty class names like L; and unterminated references.
+            if (end < 0 || end === cursor + 1)
+                return -1;
+            return end + 1;
+        }
+        default:
+            return -1;
+    }
+}
 function normalizeQuerySymbol(input, signatureMode, options) {
     if (input.kind !== "class" && input.kind !== "field" && input.kind !== "method") {
         throw invalidInputError('kind must be one of "class", "field", or "method".', {
@@ -771,9 +851,19 @@ function normalizeQuerySymbol(input, signatureMode, options) {
             querySymbol: toSymbolReference(record)
         };
     }
-    const descriptor = signatureMode === "name-only"
-        ? (input.descriptor?.trim() || "")
-        : normalizeMethodDescriptor(input.descriptor);
+    let descriptor;
+    if (signatureMode === "name-only") {
+        // name-only matches by owner+name only; a supplied descriptor is validated (so malformed
+        // input still surfaces as ERR_INVALID_INPUT) but discarded afterwards so downstream
+        // projection / filtering treats the query as "no descriptor".
+        if (input.descriptor?.trim()) {
+            normalizeMethodDescriptor(input.descriptor);
+        }
+        descriptor = "";
+    }
+    else {
+        descriptor = normalizeMethodDescriptor(input.descriptor);
+    }
     const record = createMethodSymbolRecord(owner, normalizeMemberName(normalizedName), descriptor);
     return {
         record,
@@ -811,13 +901,32 @@ function applyDisambiguationHints(candidates, disambiguation) {
     }
     const descriptorHint = normalizeDescriptorHint(disambiguation.descriptorHint);
     if (descriptorHint) {
-        const descriptorMatched = filtered.filter((candidate) => candidate.descriptor === descriptorHint);
+        const descriptorMatched = filtered.filter((candidate) => candidate.descriptor != null && candidate.descriptor === descriptorHint);
         if (descriptorMatched.length > 0) {
             filtered = descriptorMatched;
         }
     }
     return filtered;
 }
+function projectLookupCandidateDescriptor(candidate, sourceDescriptor, targetDescriptor) {
+    // Tiny mappings preserve method descriptors verbatim, so single-hop tiny paths often
+    // return the source descriptor even though the final symbol is already in the target
+    // namespace. Multi-hop paths that already produced a target-side descriptor are left
+    // unchanged by design.
+    if (candidate.kind !== "method" ||
+        !candidate.descriptor ||
+        !targetDescriptor ||
+        candidate.descriptor !== sourceDescriptor) {
+        return candidate;
+    }
+    return {
+        ...candidate,
+        descriptor: targetDescriptor
+    };
+}
+function effectiveLoomSearchProjectPath(projectPath) {
+    return normalizeOptionalProjectPath(projectPath) ?? normalizeOptionalProjectPath(process.cwd());
+}
 function collectTargetRecords(graph, targetMapping) {
     return [...(graph.recordsByTarget.get(targetMapping) ?? [])];
 }
@@ -895,6 +1004,18 @@ export class MappingService {
     fetchFn;
     graphCache = new Map();
     buildLocks = new Map();
+    resolutionCache = new Map();
+    static RESOLUTION_CACHE_MAX = 512;
+    static RESOLUTION_CACHE_TTL_MS = 5 * 60 * 1000;
+    resolutionCacheHits = 0;
+    resolutionCacheMisses = 0;
+    get resolutionCacheStats() {
+        return {
+            hits: this.resolutionCacheHits,
+            misses: this.resolutionCacheMisses,
+            size: this.resolutionCache.size
+        };
+    }
     constructor(config, versionService = new VersionService(config), fetchFn = globalThis.fetch) {
         this.config = config;
         this.versionService = versionService;
@@ -911,9 +1032,25 @@ export class MappingService {
                 }
             });
         }
-        const { record: queryRecord, querySymbol } = normalizeQuerySymbol(input, input.signatureMode, {
+        // Normalize the effective signatureMode exactly once so every downstream path — query
+        // symbol normalization, the strict-overload filter, the cache key, and warning text —
+        // sees the same value. The public tool schema defaults to "name-only", so an omitted
+        // signatureMode reaching the service (e.g. internal callers, MCP resource handlers, the
+        // resolution cache) must default to "name-only" too, otherwise the service contradicts
+        // the advertised default and silently reverts to the old descriptor-required path.
+        // Callers that genuinely need strict descriptor matching pass `signatureMode: "exact"`
+        // explicitly.
+        const effectiveSignatureMode = input.signatureMode ?? "name-only";
+        const { record: queryRecord, querySymbol } = normalizeQuerySymbol(input, effectiveSignatureMode, {
             allowShortClassName: input.kind === "class" && input.sourceMapping === "obfuscated"
         });
+        const cacheKey = this.buildResolutionCacheKey(version, input, querySymbol, effectiveSignatureMode);
+        const cached = this.resolutionCache.get(cacheKey);
+        if (cached && Date.now() - cached.cachedAt < MappingService.RESOLUTION_CACHE_TTL_MS) {
+            this.resolutionCacheHits += 1;
+            return cached.result;
+        }
+        this.resolutionCacheMisses += 1;
         const sourceMapping = input.sourceMapping;
         const targetMapping = input.targetMapping;
         if (!SUPPORTED_MAPPINGS.has(sourceMapping) || !SUPPORTED_MAPPINGS.has(targetMapping)) {
@@ -953,7 +1090,7 @@ export class MappingService {
                 warnings: []
             };
         }
-        const graph = await this.loadGraph(version, priority, requiresOnlyObfuscatedMojangGraph(sourceMapping, targetMapping) ? "obfuscated-mojang-only" : "full");
+        const graph = await this.loadGraph(version, priority, requiresOnlyObfuscatedMojangGraph(sourceMapping, targetMapping) ? "obfuscated-mojang-only" : "full", input.projectPath);
         const path = namespacePath(graph, sourceMapping, targetMapping);
         if (!path) {
             return {
@@ -968,8 +1105,54 @@ export class MappingService {
                 ]
             };
         }
-        const rawCandidates = this.mapCandidatesAlongPath(graph, path, queryRecord);
+        const descriptorProjection = queryRecord.kind === "method" && queryRecord.descriptor
+            ? this.projectMethodDescriptorToTarget(graph, path, queryRecord.descriptor)
+            : undefined;
+        // Partial projections are still useful for comparison: projectMethodDescriptorToTarget
+        // leaves unmapped `L...;` references unchanged, so JDK / external classes pass through
+        // while Minecraft class references get rewritten to the target namespace. Using the
+        // projected descriptor even when `complete === false` produces descriptors shaped like
+        // the stored records (`(Lnet/minecraft/class_1799;Ljava/lang/String;)V`) and avoids
+        // false negatives for the very common mixed MC + JDK descriptor shape.
+        const projectedDescriptor = descriptorProjection?.hadClassReferences ? descriptorProjection.descriptor : undefined;
+        let rawCandidates = this
+            .mapCandidatesAlongPath(graph, path, queryRecord)
+            .map((candidate) => queryRecord.kind === "method" && queryRecord.descriptor
+            ? projectLookupCandidateDescriptor(candidate, queryRecord.descriptor, projectedDescriptor)
+            : candidate);
         const warnings = [];
+        // signatureMode="exact" on kind=method must not return descriptorless fallback candidates
+        // (lookupCandidates adds owner+name fallbacks by design for the loose path). Without this
+        // filter a caller who supplied `foo(I)V` could be told `foo(Z)V` is the exact mapping,
+        // which would be wrong for migration tooling. Mirror resolveMethodMappingExact's strict
+        // behavior: keep only candidates whose descriptor equals the (projected) requested
+        // descriptor. If nothing passes, the normal "candidates.length === 0 -> not_found" path
+        // takes over. Partial projection is accepted here for the same reason as above — we do
+        // not reject mixed MC + JDK descriptors as mapping_unavailable just because the JDK
+        // class reference was not in the mapping graph.
+        if (queryRecord.kind === "method" &&
+            queryRecord.descriptor &&
+            effectiveSignatureMode === "exact") {
+            // Tiny v2 stores a single descriptor per method entry (typically in the obfuscated
+            // namespace) and shares it across every column, while client mappings attach a mojang
+            // descriptor on the mojang side and an obfuscated descriptor on the obfuscated side.
+            // In multi-hop paths (e.g. mojang -> obfuscated -> intermediary -> yarn) the final
+            // candidate's owner and name live in the target namespace but its descriptor can still
+            // be the obfuscated form that rode along the Tiny hop. A strict filter that compared
+            // only against the fully projected target descriptor dropped those valid candidates
+            // and produced false `not_found` for common Mojang -> Yarn lookups. Accept any
+            // candidate whose descriptor matches the caller's descriptor, the target-space
+            // projection, or the obfuscated-space projection — the three forms that actually
+            // appear in the mapping graph.
+            const strictDescriptor = projectedDescriptor ?? queryRecord.descriptor;
+            const acceptedDescriptors = new Set([queryRecord.descriptor, strictDescriptor]);
+            const toObfuscatedPath = namespacePath(graph, sourceMapping, "obfuscated");
+            if (toObfuscatedPath) {
+                const obfuscatedProjection = this.projectMethodDescriptorToTarget(graph, toObfuscatedPath, queryRecord.descriptor);
+                acceptedDescriptors.add(obfuscatedProjection.descriptor);
+            }
+            rawCandidates = rawCandidates.filter((candidate) => candidate.descriptor !== undefined && acceptedDescriptors.has(candidate.descriptor));
+        }
         const disambiguatedCandidates = applyDisambiguationHints(rawCandidates, input.disambiguation);
         if (rawCandidates.length > disambiguatedCandidates.length) {
             warnings.push(`Disambiguation hints narrowed candidates from ${rawCandidates.length} to ${disambiguatedCandidates.length}.`);
@@ -987,12 +1170,21 @@ export class MappingService {
         }
         else if (candidates.length > 1) {
             warnings.push(`Ambiguous mapping: ${candidates.length} candidates matched. Provide a stricter symbol input or disambiguation hints.`);
+            if (queryRecord.kind === "method") {
+                // find-mapping defaults to signatureMode="name-only", which discards any supplied
+                // descriptor. Telling the caller to "add descriptor" would be ineffective unless they
+                // also switch mode, so we point to the exact alternatives instead.
+                warnings.push("Retry with signatureMode=\"exact\" plus a JVM descriptor, or pass disambiguation.descriptorHint, or raise maxCandidates up to 200 to inspect the full candidate list.");
+            }
+            else {
+                warnings.push("Raise maxCandidates up to 200 to inspect the full candidate list, or use disambiguation.ownerHint to narrow the search.");
+            }
         }
         const status = candidates.length === 0 ? "not_found" : candidates.length === 1 ? "resolved" : "ambiguous";
         const ambiguityReasons = candidates.length > 1
             ? inferAmbiguityReasons(candidates, pathUsesSource(graph.pairs, path, "mojang-client-mappings"))
             : undefined;
-        return {
+        const output = {
             querySymbol,
             mappingContext,
             resolved: status === "resolved",
@@ -1005,6 +1197,9 @@ export class MappingService {
             provenance: this.provenanceForPath(graph, path),
             ambiguityReasons
         };
+        this.resolutionCache.set(cacheKey, { result: output, cachedAt: Date.now() });
+        this.trimResolutionCache();
+        return output;
     }
     async ensureMappingAvailable(input) {
         const version = input.version.trim();
@@ -1037,7 +1232,7 @@ export class MappingService {
                 warnings: []
             };
         }
-        const graph = await this.loadGraph(version, priority, requiresOnlyObfuscatedMojangGraph(sourceMapping, targetMapping) ? "obfuscated-mojang-only" : "full");
+        const graph = await this.loadGraph(version, priority, requiresOnlyObfuscatedMojangGraph(sourceMapping, targetMapping) ? "obfuscated-mojang-only" : "full", input.projectPath);
         const path = namespacePath(graph, sourceMapping, targetMapping);
         if (!path) {
             throw createError({
@@ -1121,7 +1316,7 @@ export class MappingService {
                 warnings: []
             };
         }
-        const graph = await this.loadGraph(version, priority, requiresOnlyObfuscatedMojangGraph(sourceMapping, targetMapping) ? "obfuscated-mojang-only" : "full");
+        const graph = await this.loadGraph(version, priority, requiresOnlyObfuscatedMojangGraph(sourceMapping, targetMapping) ? "obfuscated-mojang-only" : "full", input.projectPath);
         const path = namespacePath(graph, sourceMapping, targetMapping);
         if (!path) {
             return {
@@ -1137,12 +1332,16 @@ export class MappingService {
             };
         }
         const warnings = [];
+        const descriptorProjection = this.projectMethodDescriptorToTarget(graph, path, descriptor);
+        const projectedDescriptor = descriptorProjection.complete ? descriptorProjection.descriptor : undefined;
         const rawCandidates = this
             .mapCandidatesAlongPath(graph, path, queryRecord)
-            .filter((candidate) => candidate.kind === "method");
+            .filter((candidate) => candidate.kind === "method")
+            .map((candidate) => projectLookupCandidateDescriptor(candidate, descriptor, projectedDescriptor));
         const candidates = rawCandidates.map(toResolutionCandidate);
         const limitedCandidates = limitResolutionCandidates(candidates, input.maxCandidates);
-        const strictCandidates = rawCandidates.filter((candidate) => candidate.descriptor === descriptor);
+        const strictDescriptor = projectedDescriptor ?? descriptor;
+        const strictCandidates = rawCandidates.filter((candidate) => candidate.descriptor === strictDescriptor);
         if (strictCandidates.length === 1) {
             const resolved = toResolutionCandidate(strictCandidates[0]);
             return {
@@ -1160,6 +1359,9 @@ export class MappingService {
         }
         if (strictCandidates.length > 1) {
             warnings.push("Exact method mapping is ambiguous for owner+method+descriptor.");
+            if (limitedCandidates.candidatesTruncated) {
+                warnings.push("Raise maxCandidates up to 200 to inspect the full candidate list, or narrow the lookup via find-mapping disambiguation hints.");
+            }
             return {
                 querySymbol,
                 mappingContext,
@@ -1172,8 +1374,10 @@ export class MappingService {
                 provenance: this.provenanceForPath(graph, path)
             };
         }
-        if (pathUsesSource(graph.pairs, path, "mojang-client-mappings")) {
-            warnings.push("Method descriptor could not be preserved through mojang-client-mappings and exact resolution is unavailable.");
+        if (descriptorProjection.hadClassReferences && !descriptorProjection.complete) {
+            warnings.push(pathUsesSource(graph.pairs, path, "mojang-client-mappings")
+                ? "Method descriptor could not be preserved through mojang-client-mappings and exact resolution is unavailable."
+                : "Method descriptor could not be fully remapped across the mapping path and exact resolution is unavailable.");
             return {
                 querySymbol,
                 mappingContext,
@@ -1460,6 +1664,9 @@ export class MappingService {
         const buildOutput = (querySymbol, matched, status) => {
             const candidates = matched.map((record) => toResolutionCandidate(toLookupCandidate(record)));
             const limitedCandidates = limitResolutionCandidates(candidates, input.maxCandidates);
+            if (status === "ambiguous" && limitedCandidates.candidatesTruncated) {
+                warnings.push("Raise maxCandidates up to 200 to inspect the full candidate list.");
+            }
             return {
                 querySymbol,
                 mappingContext,
@@ -1502,11 +1709,40 @@ export class MappingService {
         if (input.signatureMode === "name-only") {
             const status = methodCandidates.length === 1 ? "resolved" : methodCandidates.length > 1 ? "ambiguous" : "not_found";
             if (status === "ambiguous") {
-                warnings.push(`Multiple method overloads matched name "${queryRecord.name}" in owner "${queryRecord.owner}". Provide descriptor for exact match.`);
+                // name-only discards any supplied descriptor, so telling the caller to "provide
+                // descriptor" would not disambiguate — they need to switch to signatureMode="exact".
+                warnings.push(`Multiple method overloads matched name "${queryRecord.name}" in owner "${queryRecord.owner}". Retry with signatureMode="exact" plus a JVM descriptor to pick one overload.`);
             }
             return buildOutput(querySymbol, methodCandidates, status);
         }
-        const descriptorMatched = methodCandidates.filter((record) => record.descriptor === queryRecord.descriptor);
+        // Tiny parsing stores a single descriptor per method entry (typically in the obfuscated
+        // namespace) and copies it into every namespace at load time. That means a descriptor
+        // supplied in `sourceMapping` coordinates will not string-compare equal to the record
+        // for any method whose descriptor references remapped Minecraft classes. Project the
+        // caller's descriptor to obfuscated coordinates first so class references line up with
+        // the stored record descriptors. The projection is accepted even when
+        // `projection.complete` is false: `projectMethodDescriptorToTarget` leaves every
+        // unresolvable `L...;` reference unchanged (JDK/external classes like
+        // `Ljava/lang/String;` are never in the mapping graph and pass through by design), so a
+        // partial projection still aligns the Minecraft class refs with the stored descriptor
+        // form while leaving external class refs identical to the user input. Falling back to
+        // verbatim comparison on `complete === false` would send mixed descriptors like
+        // `(Lnet/minecraft/world/item/ItemStack;Ljava/lang/String;)V` down the raw-compare path
+        // and produce false negatives in the most common lookup shape. When no class references
+        // exist at all (primitives-only descriptors such as `(I)V`) the projector marks
+        // `hadClassReferences === false` and we simply reuse the original descriptor.
+        const queryDescriptor = queryRecord.descriptor;
+        let effectiveDescriptor = queryDescriptor;
+        if (sourceMapping !== "obfuscated") {
+            const projectionPath = namespacePath(graph, sourceMapping, "obfuscated");
+            if (projectionPath) {
+                const projection = this.projectMethodDescriptorToTarget(graph, projectionPath, queryDescriptor);
+                if (projection.hadClassReferences) {
+                    effectiveDescriptor = projection.descriptor;
+                }
+            }
+        }
+        const descriptorMatched = methodCandidates.filter((record) => record.descriptor === effectiveDescriptor || record.descriptor === queryDescriptor);
         if (descriptorMatched.length === 1) {
             return buildOutput(querySymbol, descriptorMatched, "resolved");
         }
@@ -1624,6 +1860,33 @@ export class MappingService {
             descriptor: item.record.descriptor
         }));
     }
+    projectMethodDescriptorToTarget(graph, path, descriptor) {
+        let hadClassReferences = false;
+        let complete = true;
+        const classProjectionCache = new Map();
+        const projectedDescriptor = descriptor.replace(/L([^;]+);/g, (fullMatch, internalName) => {
+            hadClassReferences = true;
+            const cached = classProjectionCache.get(internalName);
+            if (cached) {
+                return `L${cached};`;
+            }
+            const projectedClassCandidates = this
+                .mapCandidatesAlongPath(graph, path, createClassSymbolRecord(internalName.replace(/\//g, ".")))
+                .filter((candidate) => candidate.kind === "class");
+            if (projectedClassCandidates.length !== 1) {
+                complete = false;
+                return fullMatch;
+            }
+            const projectedInternalName = projectedClassCandidates[0].symbol.replace(/\./g, "/");
+            classProjectionCache.set(internalName, projectedInternalName);
+            return `L${projectedInternalName};`;
+        });
+        return {
+            descriptor: projectedDescriptor,
+            hadClassReferences,
+            complete
+        };
+    }
     provenanceForPath(graph, path) {
         if (path.length <= 1) {
             return undefined;
@@ -1646,6 +1909,18 @@ export class MappingService {
     async checkMappingHealth(input) {
         const priority = mappingPriorityFromInput(this.config.mappingSourcePriority, input.sourcePriority);
         const degradations = [];
+        if (isUnobfuscatedVersion(input.version)) {
+            const requestFulfillable = input.requestedMapping === "obfuscated" || input.requestedMapping === "mojang";
+            if (!requestFulfillable) {
+                degradations.push(`Version ${input.version} is unobfuscated; ${input.requestedMapping} mappings are not applicable.`);
+            }
+            return {
+                mojangMappingsAvailable: true,
+                tinyMappingsAvailable: false,
+                memberRemapAvailable: requestFulfillable,
+                degradations
+            };
+        }
         let graph;
         try {
             graph = await this.loadGraph(input.version, priority, "full");
@@ -1692,8 +1967,9 @@ export class MappingService {
             degradations
         };
     }
-    async loadGraph(version, priority, mode) {
-        const cacheKey = `${version}|${priority}|${mode}`;
+    async loadGraph(version, priority, mode, projectPath) {
+        const effectiveProjectPath = effectiveLoomSearchProjectPath(projectPath);
+        const cacheKey = `${version}|${priority}|${mode}|${effectiveProjectPath ?? ""}`;
         const cached = this.graphCache.get(cacheKey);
         if (cached) {
             this.graphCache.delete(cacheKey);
@@ -1704,7 +1980,7 @@ export class MappingService {
         if (existingLock) {
             return existingLock;
         }
-        const buildPromise = this.buildGraph(version, priority, mode);
+        const buildPromise = this.buildGraph(version, priority, mode, effectiveProjectPath);
         this.buildLocks.set(cacheKey, buildPromise);
         try {
             const built = await buildPromise;
@@ -1716,7 +1992,7 @@ export class MappingService {
             this.buildLocks.delete(cacheKey);
         }
     }
-    async buildGraph(version, priority, mode) {
+    async buildGraph(version, priority, mode, projectPath) {
         if (isUnobfuscatedVersion(version)) {
             return {
                 version,
@@ -1749,7 +2025,7 @@ export class MappingService {
             const deferredTinyWarnings = [];
             for (const source of mappingSourceOrder(priority)) {
                 const tinyLoad = source === "loom-cache"
-                    ? await this.loadTinyPairsFromLoom(version)
+                    ? await this.loadTinyPairsFromLoom(version, projectPath)
                     : await this.loadTinyPairsFromMaven(version);
                 if (tinyLoad.pairs.size === 0) {
                     deferredTinyWarnings.push(...tinyLoad.warnings);
@@ -1847,46 +2123,67 @@ export class MappingService {
             };
         }
     }
-    async loadTinyPairsFromLoom(version) {
-        const patterns = [".gradle/loom-cache/**/*.tiny", ".gradle/loom-cache/**/*.tinyv2"];
-        const candidates = fastGlob.sync(patterns, {
-            cwd: process.cwd(),
-            absolute: true,
-            onlyFiles: true
-        });
-        const byVersion = candidates
-            .filter((p) => p.replaceAll("\\", "/").includes(`/${version}/`))
-            .sort((left, right) => left.localeCompare(right));
-        if (byVersion.length === 0) {
-            return {
-                pairs: new Map(),
-                warnings: [`No Loom tiny mapping files matched version "${version}".`],
-                mappingArtifact: "loom-cache:none"
-            };
-        }
+    async loadTinyPairsFromLoom(version, projectPath) {
+        const searchRoots = buildVersionSourceSearchRoots(effectiveLoomSearchProjectPath(projectPath));
         const merged = new Map();
-        for (const path of byVersion) {
+        const discoveredPaths = new Set();
+        for (const root of searchRoots) {
+            let discovered = [];
+            const versionRoot = join(root, version);
             try {
-                const content = await readFile(path, "utf8");
-                const parsed = parseTinyMappings(content);
-                for (const [key, index] of parsed.entries()) {
-                    const existing = merged.get(key);
-                    if (!existing) {
-                        merged.set(key, index);
-                    }
-                    else {
-                        mergeDirectionIndexes(existing, index);
-                    }
-                }
+                discovered = existsSync(versionRoot)
+                    ? await fastGlob.glob(["**/*.tiny", "**/*.tinyv2"], {
+                        cwd: versionRoot,
+                        absolute: true,
+                        onlyFiles: true
+                    })
+                    : await fastGlob.glob([`${version.replace(GLOB_SPECIAL_CHARS, "\\$&")}/**/*.tiny`, `${version.replace(GLOB_SPECIAL_CHARS, "\\$&")}/**/*.tinyv2`], {
+                        cwd: root,
+                        absolute: true,
+                        onlyFiles: true
+                    });
             }
             catch {
-                // best effort: skip unreadable or invalid files
+                continue;
             }
+            const byVersion = discovered
+                .filter((path) => path.replaceAll("\\", "/").includes(`/${version}/`))
+                .sort((left, right) => left.localeCompare(right));
+            if (byVersion.length === 0) {
+                continue;
+            }
+            for (const path of byVersion) {
+                discoveredPaths.add(path);
+                try {
+                    const content = await readFile(path, "utf8");
+                    const parsed = parseTinyMappings(content);
+                    for (const [key, index] of parsed.entries()) {
+                        const existing = merged.get(key);
+                        if (!existing) {
+                            merged.set(key, index);
+                        }
+                        else {
+                            mergeDirectionIndexes(existing, index);
+                        }
+                    }
+                }
+                catch {
+                    // best effort: skip unreadable or invalid files
+                }
+            }
+        }
+        const orderedPaths = [...discoveredPaths].sort((left, right) => left.localeCompare(right));
+        if (orderedPaths.length > 0) {
+            return {
+                pairs: merged,
+                warnings: [],
+                mappingArtifact: orderedPaths[0]
+            };
         }
         return {
-            pairs: merged,
-            warnings: [],
-            mappingArtifact: byVersion[0]
+            pairs: new Map(),
+            warnings: [`No Loom tiny mapping files matched version "${version}".`],
+            mappingArtifact: "loom-cache:none"
         };
     }
     async loadTinyPairsFromMaven(version) {
@@ -1942,15 +2239,11 @@ export class MappingService {
         };
     }
     async parseTinyFromJar(jarPath) {
-        const entries = await listJarEntries(jarPath);
-        const tinyEntries = entries
-            .filter((entry) => entry.toLowerCase().endsWith(".tiny") || entry.toLowerCase().endsWith(".tinyv2"))
-            .sort((left, right) => left.localeCompare(right));
+        const tinyEntries = (await collectMatchedJarEntriesAsUtf8(jarPath, (entry) => entry.toLowerCase().endsWith(".tiny") || entry.toLowerCase().endsWith(".tinyv2"), { continueOnError: true })).sort((left, right) => left.filePath.localeCompare(right.filePath));
         const merged = new Map();
         for (const entry of tinyEntries) {
             try {
-                const text = await readJarEntryAsUtf8(jarPath, entry);
-                const parsed = parseTinyMappings(text);
+                const parsed = parseTinyMappings(entry.content);
                 for (const [key, index] of parsed.entries()) {
                     const existing = merged.get(key);
                     if (!existing) {
@@ -2002,14 +2295,59 @@ export class MappingService {
             this.graphCache.delete(oldestKey);
         }
     }
+    // Note: in-flight buildLocks may re-populate graphCache after release.
+    // Resolution cache entries created by concurrent findMapping() calls may also
+    // survive this invalidation. Both are bounded by TTL (5 min) and will expire
+    // naturally. A full epoch-based invalidation would add complexity for a rare
+    // user-initiated operation (manage-cache).
     releaseGraphCacheEntry(version, sourcePriority) {
         const normalizedVersion = version.trim();
         if (!normalizedVersion) {
             return;
         }
         const priority = mappingPriorityFromInput(this.config.mappingSourcePriority, sourcePriority);
-        this.graphCache.delete(`${normalizedVersion}|${priority}|full`);
-        this.graphCache.delete(`${normalizedVersion}|${priority}|obfuscated-mojang-only`);
+        const prefix = `${normalizedVersion}|${priority}|`;
+        for (const key of this.graphCache.keys()) {
+            if (key.startsWith(prefix)) {
+                this.graphCache.delete(key);
+            }
+        }
+        const resolutionPrefix = `${normalizedVersion}\0`;
+        for (const key of this.resolutionCache.keys()) {
+            if (key.startsWith(resolutionPrefix)) {
+                this.resolutionCache.delete(key);
+            }
+        }
+    }
+    buildResolutionCacheKey(version, input, querySymbol, effectiveSignatureMode) {
+        return [
+            version,
+            input.kind,
+            querySymbol.symbol,
+            querySymbol.descriptor ?? "",
+            input.sourceMapping,
+            input.targetMapping,
+            input.sourcePriority ?? "",
+            effectiveLoomSearchProjectPath(input.projectPath) ?? "",
+            effectiveSignatureMode,
+            String(input.maxCandidates ?? ""),
+            JSON.stringify(input.disambiguation ?? "")
+        ].join("\0");
+    }
+    trimResolutionCache() {
+        if (this.resolutionCache.size <= MappingService.RESOLUTION_CACHE_MAX)
+            return;
+        const now = Date.now();
+        for (const [key, entry] of this.resolutionCache) {
+            if (now - entry.cachedAt > MappingService.RESOLUTION_CACHE_TTL_MS) {
+                this.resolutionCache.delete(key);
+            }
+        }
+        while (this.resolutionCache.size > MappingService.RESOLUTION_CACHE_MAX) {
+            const firstKey = this.resolutionCache.keys().next().value;
+            if (firstKey !== undefined)
+                this.resolutionCache.delete(firstKey);
+        }
     }
 }
 // ---------------------------------------------------------------------------
@@ -2039,14 +2377,13 @@ async function fetchYarnCoordinatesStandalone(version, fetchFn = globalThis.fetc
     }
 }
 async function extractTinyFromJar(jarPath, outputPath) {
-    const entries = await listJarEntries(jarPath);
-    const tinyEntry = entries.find((entry) => entry === "mappings/mappings.tiny" || entry.toLowerCase().endsWith(".tiny"));
+    const matchedEntries = await collectMatchedJarEntriesAsUtf8(jarPath, (entry) => entry === "mappings/mappings.tiny" || entry.toLowerCase().endsWith(".tiny"), { maxEntries: 1 });
+    const tinyEntry = matchedEntries[0];
     if (!tinyEntry) {
         return false;
     }
-    const content = await readJarEntryAsUtf8(jarPath, tinyEntry);
     await mkdir(dirname(outputPath), { recursive: true });
-    await writeFile(outputPath, content, "utf8");
+    await writeFile(outputPath, tinyEntry.content, "utf8");
     return true;
 }
 /**