@adhisang/minecraft-modding-mcp 1.2.1 → 2.1.0

package/dist/mapping-service.js

@@ -7,7 +7,7 @@ import { defaultDownloadPath, downloadToCache } from "./repo-downloader.js";
 import { listJarEntries, readJarEntryAsUtf8 } from "./source-jar-reader.js";
 import { VersionService, isUnobfuscatedVersion } from "./version-service.js";
 const SUPPORTED_MAPPINGS = new Set([
-    "official",
+    "obfuscated",
     "mojang",
     "intermediary",
     "yarn"
@@ -37,13 +37,21 @@ function addToSetMap(map, key, value) {
     map.set(normalizedKey, existing);
 }
 function normalizedVariants(symbol) {
-    const variants = new Set();
-    variants.add(symbol);
-    const dotted = symbol.replace(/\//g, ".");
-    variants.add(dotted);
-    const slashed = symbol.replace(/\./g, "/");
-    variants.add(slashed);
-    return [...variants];
+    const variants = [symbol];
+    let dotted;
+    if (symbol.includes("/")) {
+        dotted = symbol.replace(/\//g, ".");
+        if (dotted !== symbol) {
+            variants.push(dotted);
+        }
+    }
+    if (symbol.includes(".")) {
+        const slashed = symbol.replace(/\./g, "/");
+        if (slashed !== symbol && slashed !== dotted) {
+            variants.push(slashed);
+        }
+    }
+    return variants;
 }
 function simpleName(symbol) {
     const trimmed = symbol.trim();
@@ -230,12 +238,42 @@ function pairKey(sourceMapping, targetMapping) {
     return `${sourceMapping}->${targetMapping}`;
 }
 function parsePairKey(key) {
-    const [source, target] = key.split("->");
+    const separator = key.indexOf("->");
+    const source = separator >= 0 ? key.slice(0, separator) : key;
+    const target = separator >= 0 ? key.slice(separator + 2) : "";
     return {
         sourceMapping: source,
         targetMapping: target
     };
 }
+function buildAdjacency(pairs) {
+    const adjacency = new Map();
+    for (const key of pairs.keys()) {
+        const { sourceMapping, targetMapping } = parsePairKey(key);
+        let neighbors = adjacency.get(sourceMapping);
+        if (!neighbors) {
+            neighbors = new Set();
+            adjacency.set(sourceMapping, neighbors);
+        }
+        neighbors.add(targetMapping);
+    }
+    return new Map([...adjacency.entries()].map(([mapping, neighbors]) => [mapping, [...neighbors]]));
+}
+function buildTargetRecordIndex(pairs) {
+    const recordsByTarget = new Map();
+    for (const [key, pair] of pairs.entries()) {
+        const { targetMapping } = parsePairKey(key);
+        let bucket = recordsByTarget.get(targetMapping);
+        if (!bucket) {
+            bucket = new Map();
+            recordsByTarget.set(targetMapping, bucket);
+        }
+        for (const record of pair.index.records.values()) {
+            bucket.set(buildSymbolKey(record), record);
+        }
+    }
+    return new Map([...recordsByTarget.entries()].map(([mapping, records]) => [mapping, [...records.values()]]));
+}
 function ensurePairIndex(indexes, from, to) {
     const key = pairKey(from, to);
     const existing = indexes.get(key);
@@ -254,7 +292,7 @@ const PROGUARD_PRIMITIVES = {
 /**
  * Convert a single proguard type (e.g. "int", "net.minecraft.Foo", "int[][]")
  * to JVM notation (e.g. "I", "Lnet/minecraft/Foo;", "[[I").
- * `classLookup` maps mojang class names → official class names (for the official descriptor).
+ * `classLookup` maps mojang class names → obfuscated class names (for the obfuscated descriptor).
  * Pass `undefined` to skip class name translation (for mojang descriptors).
  */
 function proguardTypeToJvm(type, classLookup) {
@@ -294,12 +332,12 @@ function parseProguardMethod(value, classLookup) {
     return { name, descriptor: `(${paramDescriptor})${returnDescriptor}` };
 }
 function parseClientMappings(text) {
-    const officialToMojang = createDirectionIndex();
-    const mojangToOfficial = createDirectionIndex();
+    const obfuscatedToMojang = createDirectionIndex();
+    const mojangToObfuscated = createDirectionIndex();
     // Two-pass parsing: first collect class name mappings, then parse members with descriptors.
     const lines = text.split(/\r?\n/);
-    // Pass 1: collect class name mappings (mojang → official)
-    const mojangToOfficialClass = new Map();
+    // Pass 1: collect class name mappings (mojang → obfuscated)
+    const mojangToObfuscatedClass = new Map();
     let classCount = 0;
     for (const rawLine of lines) {
         const line = rawLine.trim();
@@ -309,9 +347,9 @@ function parseClientMappings(text) {
         const classMatch = /^(.+?)\s+->\s+(.+):$/.exec(line);
         if (classMatch) {
             const mojangClass = classMatch[1]?.trim() ?? "";
-            const officialClass = classMatch[2]?.trim() ?? "";
-            if (mojangClass && officialClass) {
-                mojangToOfficialClass.set(mojangClass, officialClass);
+            const obfuscatedClass = classMatch[2]?.trim() ?? "";
+            if (mojangClass && obfuscatedClass) {
+                mojangToObfuscatedClass.set(mojangClass, obfuscatedClass);
                 classCount += 1;
             }
         }
@@ -332,17 +370,17 @@ function parseClientMappings(text) {
         const classMatch = /^(.+?)\s+->\s+(.+):$/.exec(line);
         if (classMatch) {
             const mojangClass = classMatch[1]?.trim() ?? "";
-            const officialClass = classMatch[2]?.trim() ?? "";
-            if (!mojangClass || !officialClass) {
+            const obfuscatedClass = classMatch[2]?.trim() ?? "";
+            if (!mojangClass || !obfuscatedClass) {
                 currentClass = undefined;
                 continue;
             }
             currentClass = {
-                official: officialClass,
+                obfuscated: obfuscatedClass,
                 mojang: mojangClass
             };
-            addLookupEntries(officialToMojang, createClassSymbolRecord(officialClass), createClassSymbolRecord(mojangClass));
-            addLookupEntries(mojangToOfficial, createClassSymbolRecord(mojangClass), createClassSymbolRecord(officialClass));
+            addLookupEntries(obfuscatedToMojang, createClassSymbolRecord(obfuscatedClass), createClassSymbolRecord(mojangClass));
+            addLookupEntries(mojangToObfuscated, createClassSymbolRecord(mojangClass), createClassSymbolRecord(obfuscatedClass));
             continue;
         }
         if (!currentClass) {
@@ -359,31 +397,31 @@ function parseClientMappings(text) {
         }
         const mojangMemberSignature = stripLineInfo(leftRaw);
         // Try method parsing with JVM descriptor
-        const officialMethod = parseProguardMethod(mojangMemberSignature, mojangToOfficialClass);
-        if (officialMethod) {
+        const obfuscatedMethod = parseProguardMethod(mojangMemberSignature, mojangToObfuscatedClass);
+        if (obfuscatedMethod) {
             const mojangMethod = parseProguardMethod(mojangMemberSignature, undefined);
-            const officialDescriptor = officialMethod.descriptor;
+            const obfuscatedDescriptor = obfuscatedMethod.descriptor;
             const mojangDescriptor = mojangMethod?.descriptor;
-            addLookupEntries(officialToMojang, createMethodSymbolRecord(currentClass.official, rightRaw, officialDescriptor), createMethodSymbolRecord(currentClass.mojang, officialMethod.name, mojangDescriptor));
-            addLookupEntries(mojangToOfficial, createMethodSymbolRecord(currentClass.mojang, officialMethod.name, mojangDescriptor), createMethodSymbolRecord(currentClass.official, rightRaw, officialDescriptor));
+            addLookupEntries(obfuscatedToMojang, createMethodSymbolRecord(currentClass.obfuscated, rightRaw, obfuscatedDescriptor), createMethodSymbolRecord(currentClass.mojang, obfuscatedMethod.name, mojangDescriptor));
+            addLookupEntries(mojangToObfuscated, createMethodSymbolRecord(currentClass.mojang, obfuscatedMethod.name, mojangDescriptor), createMethodSymbolRecord(currentClass.obfuscated, rightRaw, obfuscatedDescriptor));
             continue;
         }
         const fieldName = parseFieldName(mojangMemberSignature);
         if (!fieldName) {
             continue;
         }
-        addLookupEntries(officialToMojang, createFieldSymbolRecord(currentClass.official, rightRaw), createFieldSymbolRecord(currentClass.mojang, fieldName));
-        addLookupEntries(mojangToOfficial, createFieldSymbolRecord(currentClass.mojang, fieldName), createFieldSymbolRecord(currentClass.official, rightRaw));
+        addLookupEntries(obfuscatedToMojang, createFieldSymbolRecord(currentClass.obfuscated, rightRaw), createFieldSymbolRecord(currentClass.mojang, fieldName));
+        addLookupEntries(mojangToObfuscated, createFieldSymbolRecord(currentClass.mojang, fieldName), createFieldSymbolRecord(currentClass.obfuscated, rightRaw));
     }
     const result = new Map();
-    result.set(pairKey("official", "mojang"), officialToMojang);
-    result.set(pairKey("mojang", "official"), mojangToOfficial);
+    result.set(pairKey("obfuscated", "mojang"), obfuscatedToMojang);
+    result.set(pairKey("mojang", "obfuscated"), mojangToObfuscated);
     return result;
 }
 function normalizeTinyNamespace(namespace) {
     const normalized = namespace.trim().toLowerCase();
-    if (normalized === "official") {
-        return "official";
+    if (normalized === "obfuscated") {
+        return "obfuscated";
     }
     if (normalized === "mojang") {
         return "mojang";
@@ -552,38 +590,48 @@ function mappingSourceOrder(priority) {
     }
     return ["loom-cache", "maven"];
 }
-function namespacePath(pairs, sourceMapping, targetMapping) {
+function namespacePath(graph, sourceMapping, targetMapping) {
     if (sourceMapping === targetMapping) {
         return [sourceMapping];
     }
+    const key = pairKey(sourceMapping, targetMapping);
+    if (graph.pathCache.has(key)) {
+        return graph.pathCache.get(key);
+    }
+    const { adjacency } = graph;
     const queue = [sourceMapping];
+    let queueIndex = 0;
     const parent = new Map([[sourceMapping, undefined]]);
-    while (queue.length > 0) {
-        const current = queue.shift();
+    while (queueIndex < queue.length) {
+        const current = queue[queueIndex];
+        queueIndex += 1;
         if (current === targetMapping) {
             break;
         }
-        for (const key of pairs.keys()) {
-            const parsed = parsePairKey(key);
-            if (parsed.sourceMapping !== current) {
-                continue;
-            }
-            if (parent.has(parsed.targetMapping)) {
+        const neighbors = adjacency.get(current);
+        if (!neighbors) {
+            continue;
+        }
+        for (const neighbor of neighbors) {
+            if (parent.has(neighbor)) {
                 continue;
             }
-            parent.set(parsed.targetMapping, current);
-            queue.push(parsed.targetMapping);
+            parent.set(neighbor, current);
+            queue.push(neighbor);
         }
     }
     if (!parent.has(targetMapping)) {
+        graph.pathCache.set(key, undefined);
         return undefined;
     }
-    const path = [];
+    const reversedPath = [];
     let cursor = targetMapping;
     while (cursor) {
-        path.unshift(cursor);
+        reversedPath.push(cursor);
         cursor = parent.get(cursor);
     }
+    const path = reversedPath.reverse();
+    graph.pathCache.set(key, path);
     return path;
 }
 function pathUsesSource(pairs, path, source) {
@@ -765,17 +813,7 @@ function applyDisambiguationHints(candidates, disambiguation) {
     return filtered;
 }
 function collectTargetRecords(graph, targetMapping) {
-    const merged = new Map();
-    for (const [key, pair] of graph.pairs.entries()) {
-        const parsed = parsePairKey(key);
-        if (parsed.targetMapping !== targetMapping) {
-            continue;
-        }
-        for (const record of pair.index.records.values()) {
-            merged.set(buildSymbolKey(record), record);
-        }
-    }
-    return [...merged.values()];
+    return [...(graph.recordsByTarget.get(targetMapping) ?? [])];
 }
 function normalizeIncludedKinds(inputKinds) {
     const normalized = new Set();
@@ -823,6 +861,28 @@ function inferAmbiguityReasons(candidates, usedMojangClientMappings) {
     }
     return reasons;
 }
+function clampCandidateLimit(limit) {
+    if (!Number.isFinite(limit) || limit == null) {
+        return MAX_CANDIDATES;
+    }
+    return Math.max(1, Math.min(MAX_CANDIDATES, Math.trunc(limit)));
+}
+function limitResolutionCandidates(candidates, requestedLimit) {
+    const candidateCount = candidates.length;
+    const limit = clampCandidateLimit(requestedLimit);
+    const limitedCandidates = candidateCount > limit ? candidates.slice(0, limit) : candidates;
+    return {
+        candidates: limitedCandidates,
+        candidateCount,
+        ...(limitedCandidates.length < candidateCount ? { candidatesTruncated: true } : {})
+    };
+}
+function clampRowLimit(limit) {
+    if (!Number.isFinite(limit) || limit == null) {
+        return undefined;
+    }
+    return Math.max(1, Math.min(5000, Math.trunc(limit)));
+}
 export class MappingService {
     config;
     versionService;
@@ -845,7 +905,7 @@ export class MappingService {
                 }
             });
         }
-        const { record: queryRecord, querySymbol } = normalizeQuerySymbol(input);
+        const { record: queryRecord, querySymbol } = normalizeQuerySymbol(input, input.signatureMode);
         const sourceMapping = input.sourceMapping;
         const targetMapping = input.targetMapping;
         if (!SUPPORTED_MAPPINGS.has(sourceMapping) || !SUPPORTED_MAPPINGS.has(targetMapping)) {
@@ -872,18 +932,21 @@ export class MappingService {
                 matchKind: "exact",
                 confidence: 1
             });
+            const limited = limitResolutionCandidates([identity], input.maxCandidates);
             return {
                 querySymbol,
                 mappingContext,
                 resolved: true,
                 status: "resolved",
                 resolvedSymbol: querySymbol,
-                candidates: [identity],
+                candidates: limited.candidates,
+                candidateCount: limited.candidateCount,
+                candidatesTruncated: limited.candidatesTruncated,
                 warnings: []
             };
         }
         const graph = await this.loadGraph(version, priority);
-        const path = namespacePath(graph.pairs, sourceMapping, targetMapping);
+        const path = namespacePath(graph, sourceMapping, targetMapping);
         if (!path) {
             return {
                 querySymbol,
@@ -891,6 +954,7 @@ export class MappingService {
                 resolved: false,
                 status: "mapping_unavailable",
                 candidates: [],
+                candidateCount: 0,
                 warnings: [
                     `No mapping path is available for ${sourceMapping} -> ${targetMapping} on version "${version}".`
                 ]
@@ -903,6 +967,7 @@ export class MappingService {
             warnings.push(`Disambiguation hints narrowed candidates from ${rawCandidates.length} to ${disambiguatedCandidates.length}.`);
         }
         const candidates = disambiguatedCandidates.map(toResolutionCandidate);
+        const limitedCandidates = limitResolutionCandidates(candidates, input.maxCandidates);
         if (queryRecord.kind === "method" &&
             queryRecord.descriptor &&
             pathUsesSource(graph.pairs, path, "mojang-client-mappings") &&
@@ -925,7 +990,9 @@ export class MappingService {
             resolved: status === "resolved",
             status,
             resolvedSymbol: status === "resolved" ? candidates[0] : undefined,
-            candidates,
+            candidates: limitedCandidates.candidates,
+            candidateCount: limitedCandidates.candidateCount,
+            candidatesTruncated: limitedCandidates.candidatesTruncated,
             warnings,
             provenance: this.provenanceForPath(graph, path),
             ambiguityReasons
@@ -963,7 +1030,7 @@ export class MappingService {
             };
         }
         const graph = await this.loadGraph(version, priority);
-        const path = namespacePath(graph.pairs, sourceMapping, targetMapping);
+        const path = namespacePath(graph, sourceMapping, targetMapping);
         if (!path) {
             throw createError({
                 code: ERROR_CODES.MAPPING_UNAVAILABLE,
@@ -973,8 +1040,8 @@ export class MappingService {
                     sourceMapping,
                     targetMapping,
                     sourcePriority: priority,
-                    nextAction: "Try mapping=official which is always available.",
-                    suggestedCall: { tool: "resolve-artifact", params: { mapping: "official" } }
+                    nextAction: "Try mapping=obfuscated which is always available.",
+                    suggestedCall: { tool: "resolve-artifact", params: { mapping: "obfuscated" } }
                 }
             });
         }
@@ -1000,16 +1067,10 @@ export class MappingService {
                 }
             });
         }
-        if (input.kind !== "method") {
-            throw createError({
-                code: ERROR_CODES.INVALID_INPUT,
-                message: 'resolveMethodMappingExact requires kind="method".',
-                details: {
-                    kind: input.kind
-                }
-            });
-        }
-        const { record: queryRecord, querySymbol } = normalizeQuerySymbol(input);
+        const { record: queryRecord, querySymbol } = normalizeQuerySymbol({
+            ...input,
+            kind: "method"
+        });
         const owner = queryRecord.owner;
         const method = queryRecord.name;
         const descriptor = queryRecord.descriptor;
@@ -1039,18 +1100,21 @@ export class MappingService {
                 matchKind: "exact",
                 confidence: 1
             });
+            const limited = limitResolutionCandidates([resolvedCandidate], input.maxCandidates);
             return {
                 querySymbol,
                 mappingContext,
                 resolved: true,
                 status: "resolved",
                 resolvedSymbol: resolvedCandidate,
-                candidates: [resolvedCandidate],
+                candidates: limited.candidates,
+                candidateCount: limited.candidateCount,
+                candidatesTruncated: limited.candidatesTruncated,
                 warnings: []
             };
         }
         const graph = await this.loadGraph(version, priority);
-        const path = namespacePath(graph.pairs, sourceMapping, targetMapping);
+        const path = namespacePath(graph, sourceMapping, targetMapping);
         if (!path) {
             return {
                 querySymbol,
@@ -1058,6 +1122,7 @@ export class MappingService {
                 resolved: false,
                 status: "mapping_unavailable",
                 candidates: [],
+                candidateCount: 0,
                 warnings: [
                     `No mapping path is available for ${sourceMapping} -> ${targetMapping} on version "${version}".`
                 ]
@@ -1068,6 +1133,7 @@ export class MappingService {
             .mapCandidatesAlongPath(graph, path, queryRecord)
             .filter((candidate) => candidate.kind === "method");
         const candidates = rawCandidates.map(toResolutionCandidate);
+        const limitedCandidates = limitResolutionCandidates(candidates, input.maxCandidates);
         const strictCandidates = rawCandidates.filter((candidate) => candidate.descriptor === descriptor);
         if (strictCandidates.length === 1) {
             const resolved = toResolutionCandidate(strictCandidates[0]);
@@ -1077,7 +1143,9 @@ export class MappingService {
                 resolved: true,
                 status: "resolved",
                 resolvedSymbol: resolved,
-                candidates,
+                candidates: limitedCandidates.candidates,
+                candidateCount: limitedCandidates.candidateCount,
+                candidatesTruncated: limitedCandidates.candidatesTruncated,
                 warnings,
                 provenance: this.provenanceForPath(graph, path)
             };
@@ -1089,7 +1157,9 @@ export class MappingService {
                 mappingContext,
                 resolved: false,
                 status: "ambiguous",
-                candidates,
+                candidates: limitedCandidates.candidates,
+                candidateCount: limitedCandidates.candidateCount,
+                candidatesTruncated: limitedCandidates.candidatesTruncated,
                 warnings,
                 provenance: this.provenanceForPath(graph, path)
             };
@@ -1101,7 +1171,9 @@ export class MappingService {
                 mappingContext,
                 resolved: false,
                 status: "mapping_unavailable",
-                candidates,
+                candidates: limitedCandidates.candidates,
+                candidateCount: limitedCandidates.candidateCount,
+                candidatesTruncated: limitedCandidates.candidatesTruncated,
                 warnings,
                 provenance: this.provenanceForPath(graph, path)
             };
@@ -1111,7 +1183,9 @@ export class MappingService {
             mappingContext,
             resolved: false,
             status: "not_found",
-            candidates,
+            candidates: limitedCandidates.candidates,
+            candidateCount: limitedCandidates.candidateCount,
+            candidatesTruncated: limitedCandidates.candidatesTruncated,
             warnings,
             provenance: this.provenanceForPath(graph, path)
         };
@@ -1143,6 +1217,19 @@ export class MappingService {
         const graph = await this.loadGraph(version, priority);
         const warnings = [...graph.warnings];
         const includeKinds = normalizeIncludedKinds(input.includeKinds);
+        const pathCache = new Map();
+        const resolvePath = (sourceMapping, targetMapping) => {
+            if (sourceMapping === targetMapping) {
+                return [sourceMapping];
+            }
+            const key = pairKey(sourceMapping, targetMapping);
+            if (pathCache.has(key)) {
+                return pathCache.get(key);
+            }
+            const path = namespacePath(graph, sourceMapping, targetMapping);
+            pathCache.set(key, path);
+            return path;
+        };
         const classByMapping = {
             [classNameMapping]: createClassSymbolRecord(className)
         };
@@ -1150,7 +1237,7 @@ export class MappingService {
             if (mapping === classNameMapping) {
                 continue;
             }
-            const mapped = this.mapRecordBetweenMappings(graph, classNameMapping, mapping, classByMapping[classNameMapping]);
+            const mapped = this.mapRecordBetweenMappings(graph, classNameMapping, mapping, classByMapping[classNameMapping], resolvePath(classNameMapping, mapping));
             if (mapped.length > 1) {
                 const competing = mapped.slice(0, 5).map((c) => c.symbol);
                 warnings.push(`Class identity mapping to ${mapping} is ambiguous for "${className}": competing=[${competing.join(", ")}].`);
@@ -1159,7 +1246,7 @@ export class MappingService {
                 classByMapping[mapping] = mapped[0];
             }
         }
-        const baseMapping = classByMapping.official ? "official" : classNameMapping;
+        const baseMapping = classByMapping.obfuscated ? "obfuscated" : classNameMapping;
         const baseClass = classByMapping[baseMapping];
         if (!baseClass) {
             return {
@@ -1167,12 +1254,13 @@ export class MappingService {
                 className,
                 classNameMapping,
                 classIdentity: {
-                    official: classByMapping.official?.symbol,
+                    obfuscated: classByMapping.obfuscated?.symbol,
                     mojang: classByMapping.mojang?.symbol,
                     intermediary: classByMapping.intermediary?.symbol,
                     yarn: classByMapping.yarn?.symbol
                 },
                 rows: [],
+                rowCount: 0,
                 warnings
             };
         }
@@ -1226,7 +1314,7 @@ export class MappingService {
                     resolved = baseRecord;
                 }
                 else {
-                    const mapped = this.mapRecordBetweenMappings(graph, baseMapping, mapping, baseRecord);
+                    const mapped = this.mapRecordBetweenMappings(graph, baseMapping, mapping, baseRecord, resolvePath(baseMapping, mapping));
                     let filtered = mapped;
                     if (baseRecord.kind !== "class" && classIdentity) {
                         filtered = filtered.filter((candidate) => candidate.owner === classIdentity.symbol);
@@ -1255,23 +1343,28 @@ export class MappingService {
                 };
                 row[mapping] = entry;
             }
-            row.completeness = Boolean(row.official && row.mojang && row.intermediary && row.yarn);
+            row.completeness = Boolean(row.obfuscated && row.mojang && row.intermediary && row.yarn);
             rows.push(row);
             if (rowHadAmbiguity) {
                 ambiguousRowCount += 1;
             }
         }
+        const rowCount = rows.length;
+        const rowLimit = clampRowLimit(input.maxRows);
+        const limitedRows = rowLimit != null && rowCount > rowLimit ? rows.slice(0, rowLimit) : rows;
         return {
             version,
             className,
             classNameMapping,
             classIdentity: {
-                official: classByMapping.official?.symbol,
+                obfuscated: classByMapping.obfuscated?.symbol,
                 mojang: classByMapping.mojang?.symbol,
                 intermediary: classByMapping.intermediary?.symbol,
                 yarn: classByMapping.yarn?.symbol
             },
-            rows,
+            rows: limitedRows,
+            rowCount,
+            rowsTruncated: limitedRows.length < rowCount ? true : undefined,
             warnings,
             ambiguousRowCount: ambiguousRowCount > 0 ? ambiguousRowCount : undefined
         };
@@ -1352,18 +1445,22 @@ export class MappingService {
                 resolved: false,
                 status: "mapping_unavailable",
                 candidates: [],
+                candidateCount: 0,
                 warnings
             };
         }
         const buildOutput = (querySymbol, matched, status) => {
             const candidates = matched.map((record) => toResolutionCandidate(toLookupCandidate(record)));
+            const limitedCandidates = limitResolutionCandidates(candidates, input.maxCandidates);
             return {
                 querySymbol,
                 mappingContext,
                 resolved: status === "resolved",
                 status,
                 resolvedSymbol: status === "resolved" ? candidates[0] : undefined,
-                candidates,
+                candidates: limitedCandidates.candidates,
+                candidateCount: limitedCandidates.candidateCount,
+                candidatesTruncated: limitedCandidates.candidatesTruncated,
                 warnings
             };
         };
@@ -1414,11 +1511,11 @@ export class MappingService {
         }
         return buildOutput(querySymbol, [], "not_found");
     }
-    mapRecordBetweenMappings(graph, sourceMapping, targetMapping, record) {
+    mapRecordBetweenMappings(graph, sourceMapping, targetMapping, record, resolvedPath) {
         if (sourceMapping === targetMapping) {
             return [record];
         }
-        const path = namespacePath(graph.pairs, sourceMapping, targetMapping);
+        const path = resolvedPath ?? namespacePath(graph, sourceMapping, targetMapping);
         if (!path) {
             return [];
         }
@@ -1568,16 +1665,16 @@ export class MappingService {
         if (!tinyAvailable) {
             degradations.push("No intermediary/yarn tiny mappings were found for this version.");
         }
-        // Check if member remap path exists (requestedMapping → official)
+        // Check if member remap path exists (requestedMapping → obfuscated)
         let memberRemapAvailable = false;
-        if (input.requestedMapping === "official") {
+        if (input.requestedMapping === "obfuscated") {
             memberRemapAvailable = true;
         }
         else {
-            const path = namespacePath(graph.pairs, input.requestedMapping, "official");
+            const path = namespacePath(graph, input.requestedMapping, "obfuscated");
             memberRemapAvailable = path != null && path.length > 1;
             if (!memberRemapAvailable) {
-                degradations.push(`No mapping path from ${input.requestedMapping} to official; member remap will fail.`);
+                degradations.push(`No mapping path from ${input.requestedMapping} to obfuscated; member remap will fail.`);
             }
         }
         return {
@@ -1617,8 +1714,11 @@ export class MappingService {
                 version,
                 priority,
                 pairs: new Map(),
+                adjacency: new Map(),
+                pathCache: new Map(),
+                recordsByTarget: new Map(),
                 warnings: [
-                    `Version ${version} is unobfuscated; mapping graph is empty (official names are final).`
+                    `Version ${version} is unobfuscated; mapping graph is empty because the runtime already uses deobfuscated names.`
                 ]
             };
         }
@@ -1626,27 +1726,38 @@ export class MappingService {
             version,
             priority,
             pairs: new Map(),
+            adjacency: new Map(),
+            pathCache: new Map(),
+            recordsByTarget: new Map(),
             warnings: []
         };
         const mojangLoad = await this.loadMojangPairs(version);
         graph.warnings.push(...mojangLoad.warnings);
         this.mergePairs(graph.pairs, mojangLoad.pairs, "mojang-client-mappings", mojangLoad.mappingArtifact);
         let tinyLoaded = false;
+        const deferredTinyWarnings = [];
         for (const source of mappingSourceOrder(priority)) {
             const tinyLoad = source === "loom-cache"
                 ? await this.loadTinyPairsFromLoom(version)
                 : await this.loadTinyPairsFromMaven(version);
-            graph.warnings.push(...tinyLoad.warnings);
             if (tinyLoad.pairs.size === 0) {
+                deferredTinyWarnings.push(...tinyLoad.warnings);
                 continue;
             }
             tinyLoaded = true;
             this.mergePairs(graph.pairs, tinyLoad.pairs, source, tinyLoad.mappingArtifact);
+            graph.warnings.push(...tinyLoad.warnings);
+            if (deferredTinyWarnings.length > 0) {
+                graph.warnings.push(`Used ${source === "maven" ? "Maven" : "Loom cache"} tiny mappings for "${version}" after an earlier source lookup returned no data.`);
+            }
             break;
         }
         if (!tinyLoaded) {
+            graph.warnings.push(...deferredTinyWarnings);
             graph.warnings.push("No intermediary/yarn tiny mappings were found for this version.");
         }
+        graph.adjacency = buildAdjacency(graph.pairs);
+        graph.recordsByTarget = buildTargetRecordIndex(graph.pairs);
         return graph;
     }
     mergePairs(target, source, pairSource, mappingArtifact) {
@@ -1769,31 +1880,37 @@ export class MappingService {
     async loadTinyPairsFromMaven(version) {
         const warnings = [];
         const merged = new Map();
-        const attemptedArtifacts = [];
         const repos = this.config.sourceRepos;
         const intermediaryUrls = [];
         const yarnUrls = [];
-        for (const repo of repos) {
-            const base = repo.replace(/\/+$/, "");
+        const repoBases = repos.map((repo) => repo.replace(/\/+$/, ""));
+        const yarnCoordinatesByRepo = await Promise.all(repoBases.map(async (base) => ({
+            base,
+            yarnCoordinates: await this.fetchYarnCoordinates(base, version)
+        })));
+        for (const { base, yarnCoordinates } of yarnCoordinatesByRepo) {
             intermediaryUrls.push(`${base}/net/fabricmc/intermediary/${version}/intermediary-${version}-v2.jar`, `${base}/net/fabricmc/intermediary/${version}/intermediary-${version}.jar`);
-            const yarnCoordinates = await this.fetchYarnCoordinates(base, version);
             for (const coordinate of yarnCoordinates) {
                 yarnUrls.push(`${base}/net/fabricmc/yarn/${coordinate}/yarn-${coordinate}-v2.jar`, `${base}/net/fabricmc/yarn/${coordinate}/yarn-${coordinate}.jar`);
             }
         }
         const allUrls = [...intermediaryUrls, ...yarnUrls];
-        for (const url of allUrls) {
-            attemptedArtifacts.push(url);
+        const parsedResults = await Promise.allSettled(allUrls.map(async (url) => {
             const downloaded = await downloadToCache(url, defaultDownloadPath(this.config.cacheDir, url), {
                 fetchFn: this.fetchFn,
                 retries: this.config.fetchRetries,
                 timeoutMs: this.config.fetchTimeoutMs
             });
             if (!downloaded.ok || !downloaded.path) {
+                return undefined;
+            }
+            return this.parseTinyFromJar(downloaded.path);
+        }));
+        for (const result of parsedResults) {
+            if (result.status !== "fulfilled" || !result.value) {
                 continue;
             }
-            const parsed = await this.parseTinyFromJar(downloaded.path);
-            for (const [key, index] of parsed.entries()) {
+            for (const [key, index] of result.value.entries()) {
                 const existing = merged.get(key);
                 if (!existing) {
                     merged.set(key, index);
@@ -1809,7 +1926,7 @@ export class MappingService {
         return {
             pairs: merged,
             warnings,
-            mappingArtifact: attemptedArtifacts[0] ?? "maven:none"
+            mappingArtifact: allUrls[0] ?? "maven:none"
         };
     }
     async parseTinyFromJar(jarPath) {