@adhisang/minecraft-modding-mcp 3.2.0 → 4.1.0

package/dist/mapping-service.js

@@ -1,921 +1,43 @@
 import { existsSync } from "node:fs";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import fastGlob from "fast-glob";
+import { buildSuggestedCall } from "./build-suggested-call.js";
 import { createError, ERROR_CODES } from "./errors.js";
-import { buildVersionSourceSearchRoots, normalizeOptionalProjectPath } from "./gradle-paths.js";
 import { defaultDownloadPath, downloadToCache } from "./repo-downloader.js";
 import { collectMatchedJarEntriesAsUtf8 } from "./source-jar-reader.js";
 import { VersionService, isUnobfuscatedVersion } from "./version-service.js";
+import { buildSymbolKey, createClassSymbolRecord, mergeDirectionIndexes, normalizeMappedSymbolOutput } from "./mapping/parsers/symbol-records.js";
+import { buildAdjacency, buildTargetRecordIndex, pairKey } from "./mapping/parsers/normalize.js";
+import { MATCH_RANK, MAX_CANDIDATES } from "./mapping/internal-types.js";
+import { applyDisambiguationHints, clampRowLimit, collectTargetRecords, effectiveLoomSearchProjectPath, inferAmbiguityReasons, invalidInputError, limitResolutionCandidates, lookupCandidates, mappingPriorityFromInput, mappingSourceOrder, namespacePath, normalizeIncludedKinds, normalizeQuerySymbol, pathToTransformChain, pathUsesSource, projectLookupCandidateDescriptor, requiresOnlyObfuscatedMojangGraph, toLookupCandidate, toResolutionCandidate } from "./mapping/lookup.js";
+import { loadMojangPairs } from "./mapping/loaders/mojang.js";
+import { loadTinyPairsFromLoom } from "./mapping/loaders/tiny-loom.js";
+import { loadTinyPairsFromMaven } from "./mapping/loaders/tiny-maven.js";
 const SUPPORTED_MAPPINGS = new Set([
     "obfuscated",
     "mojang",
     "intermediary",
     "yarn"
 ]);
-const MATCH_RANK = {
-    exact: 3,
-    normalized: 2,
-    "simple-name": 1
-};
-const DESCRIPTOR_FALLBACK_CONFIDENCE = 0.85;
-const MAX_CANDIDATES = 200;
-const GLOB_SPECIAL_CHARS = /[\\!*+?()[\]{}@|]/g;
-function createDirectionIndex() {
-    return {
-        exact: new Map(),
-        normalized: new Map(),
-        simple: new Map(),
-        records: new Map()
-    };
-}
-function addToSetMap(map, key, value) {
-    const normalizedKey = key.trim();
-    if (!normalizedKey) {
-        return;
-    }
-    const existing = map.get(normalizedKey) ?? new Set();
-    existing.add(value);
-    map.set(normalizedKey, existing);
-}
-function normalizedVariants(symbol) {
-    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();
-    if (!trimmed) {
-        return undefined;
-    }
-    const withoutDescriptor = trimmed.includes("(") ? trimmed.slice(0, trimmed.indexOf("(")) : trimmed;
-    const base = withoutDescriptor.split(/[./]/).at(-1)?.trim();
-    return base || undefined;
-}
-function normalizeMappedSymbolOutput(symbol) {
-    return symbol.replace(/\//g, ".");
-}
-function splitOwnerAndName(symbol) {
-    const trimmed = symbol.trim();
-    const separatorIndex = Math.max(trimmed.lastIndexOf("."), trimmed.lastIndexOf("/"));
-    if (separatorIndex <= 0 || separatorIndex >= trimmed.length - 1) {
-        return undefined;
-    }
-    return {
-        owner: trimmed.slice(0, separatorIndex),
-        name: trimmed.slice(separatorIndex + 1)
-    };
-}
-function stripLineInfo(input) {
-    let value = input.trim();
-    while (/^\d+:\d+:/.test(value)) {
-        value = value.replace(/^\d+:\d+:/, "");
-    }
-    return value.replace(/:\d+:\d+$/, "").trim();
-}
-function parseMethodName(value) {
-    const match = /^(.+?)\s+([^\s(]+)\((.*)\)$/.exec(value);
-    if (!match) {
-        return undefined;
-    }
-    return match[2]?.trim() || undefined;
-}
-function parseFieldName(value) {
-    const match = /^(.+?)\s+([^\s]+)$/.exec(value);
-    if (!match) {
-        return undefined;
-    }
-    return match[2]?.trim() || undefined;
-}
-function buildSymbolKey(record) {
-    return `${record.kind}|${record.owner ?? ""}|${record.name}|${record.descriptor ?? ""}`;
-}
-function classNameParts(classFqn) {
-    const separatorIndex = classFqn.lastIndexOf(".");
-    if (separatorIndex <= 0 || separatorIndex >= classFqn.length - 1) {
-        return {
-            owner: undefined,
-            name: classFqn
-        };
-    }
-    return {
-        owner: classFqn.slice(0, separatorIndex),
-        name: classFqn.slice(separatorIndex + 1)
-    };
-}
-function createClassSymbolRecord(className) {
-    const symbol = normalizeMappedSymbolOutput(className.trim());
-    const parts = classNameParts(symbol);
-    return {
-        kind: "class",
-        symbol,
-        owner: parts.owner,
-        name: parts.name
-    };
-}
-function createFieldSymbolRecord(owner, fieldName) {
-    const normalizedOwner = normalizeMappedSymbolOutput(owner.trim());
-    const normalizedName = fieldName.trim();
-    return {
-        kind: "field",
-        symbol: `${normalizedOwner}.${normalizedName}`,
-        owner: normalizedOwner,
-        name: normalizedName
-    };
-}
-function createMethodSymbolRecord(owner, methodName, descriptor) {
-    const normalizedOwner = normalizeMappedSymbolOutput(owner.trim());
-    const normalizedName = methodName.trim();
-    const normalizedDescriptor = descriptor?.trim() || undefined;
-    return {
-        kind: "method",
-        symbol: `${normalizedOwner}.${normalizedName}${normalizedDescriptor ?? ""}`,
-        owner: normalizedOwner,
-        name: normalizedName,
-        descriptor: normalizedDescriptor
-    };
-}
-function parseInputSymbol(symbol) {
-    const trimmed = symbol.trim();
-    if (!trimmed || /\s/.test(trimmed)) {
-        return undefined;
-    }
-    const openIndex = trimmed.indexOf("(");
-    if (openIndex >= 0) {
-        const closeIndex = trimmed.indexOf(")", openIndex);
-        if (closeIndex < 0) {
-            return undefined;
-        }
-        const ownerAndMethod = splitOwnerAndName(trimmed.slice(0, openIndex));
-        if (!ownerAndMethod) {
-            return undefined;
-        }
-        const descriptor = trimmed.slice(openIndex);
-        return createMethodSymbolRecord(ownerAndMethod.owner, ownerAndMethod.name, descriptor);
-    }
-    const ownerAndName = splitOwnerAndName(trimmed);
-    if (!ownerAndName) {
-        return createClassSymbolRecord(trimmed);
-    }
-    if (/^[A-Z$]/.test(ownerAndName.name)) {
-        return createClassSymbolRecord(trimmed);
-    }
-    return createFieldSymbolRecord(ownerAndName.owner, ownerAndName.name);
-}
-function exactLookupKeys(record) {
-    const keys = new Set([record.symbol]);
-    if (record.kind === "method" && record.owner && record.descriptor) {
-        keys.add(`${record.owner}.${record.name}`);
-    }
-    return [...keys];
-}
-function simpleLookupKeys(record) {
-    if (record.kind === "class") {
-        return [record.name];
-    }
-    if (record.kind === "field") {
-        return [record.name];
-    }
-    if (record.descriptor) {
-        return [record.name, `${record.name}${record.descriptor}`];
-    }
-    return [record.name];
-}
-function registerRecord(index, record) {
-    const key = buildSymbolKey(record);
-    if (!index.records.has(key)) {
-        index.records.set(key, record);
-    }
-    return key;
-}
-function addLookupEntries(index, fromRecord, toRecord) {
-    if (!fromRecord.symbol || !toRecord.symbol) {
-        return;
-    }
-    const targetKey = registerRecord(index, toRecord);
-    for (const key of exactLookupKeys(fromRecord)) {
-        addToSetMap(index.exact, key, targetKey);
-        for (const variant of normalizedVariants(key)) {
-            if (variant !== key) {
-                addToSetMap(index.normalized, variant, targetKey);
-            }
-        }
-    }
-    for (const key of simpleLookupKeys(fromRecord)) {
-        addToSetMap(index.simple, key, targetKey);
-    }
-}
-function mergeDirectionIndexes(target, source) {
-    const mergeMap = (targetMap, sourceMap) => {
-        for (const [key, values] of sourceMap.entries()) {
-            const existing = targetMap.get(key) ?? new Set();
-            for (const value of values) {
-                existing.add(value);
-            }
-            targetMap.set(key, existing);
-        }
-    };
-    mergeMap(target.exact, source.exact);
-    mergeMap(target.normalized, source.normalized);
-    mergeMap(target.simple, source.simple);
-    for (const [key, value] of source.records.entries()) {
-        if (!target.records.has(key)) {
-            target.records.set(key, value);
-        }
-    }
-}
-function pairKey(sourceMapping, targetMapping) {
-    return `${sourceMapping}->${targetMapping}`;
-}
-function parsePairKey(key) {
-    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);
-    if (existing) {
-        return existing;
-    }
-    const created = createDirectionIndex();
-    indexes.set(key, created);
-    return created;
-}
-/** Map of proguard primitive type names to JVM type characters. */
-const PROGUARD_PRIMITIVES = {
-    void: "V", boolean: "Z", byte: "B", char: "C",
-    short: "S", int: "I", long: "J", float: "F", double: "D"
-};
-/**
- * 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 → obfuscated class names (for the obfuscated descriptor).
- * Pass `undefined` to skip class name translation (for mojang descriptors).
- */
-function proguardTypeToJvm(type, classLookup) {
-    let arrayDepth = 0;
-    let base = type;
-    while (base.endsWith("[]")) {
-        arrayDepth += 1;
-        base = base.slice(0, -2);
-    }
-    const prefix = "[".repeat(arrayDepth);
-    const primitive = PROGUARD_PRIMITIVES[base];
-    if (primitive) {
-        return `${prefix}${primitive}`;
-    }
-    const translated = classLookup ? (classLookup.get(base) ?? base) : base;
-    return `${prefix}L${translated.replace(/\./g, "/")};`;
-}
-/**
- * Parse a proguard method signature (after stripLineInfo) into a JVM descriptor.
- * Input format: "returnType methodName(paramType1,paramType2,...)"
- * Returns `{ name, descriptor }` or `undefined` if parsing fails.
- */
-function parseProguardMethod(value, classLookup) {
-    const match = /^(.+?)\s+([^\s(]+)\((.*)\)$/.exec(value);
-    if (!match) {
-        return undefined;
-    }
-    const returnType = match[1].trim();
-    const name = match[2].trim();
-    const params = match[3].trim();
-    if (!name) {
-        return undefined;
-    }
-    const paramParts = params ? params.split(",").map((p) => p.trim()) : [];
-    const paramDescriptor = paramParts.map((p) => proguardTypeToJvm(p, classLookup)).join("");
-    const returnDescriptor = proguardTypeToJvm(returnType, classLookup);
-    return { name, descriptor: `(${paramDescriptor})${returnDescriptor}` };
-}
-function parseClientMappings(text) {
-    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 → obfuscated)
-    const mojangToObfuscatedClass = new Map();
-    let classCount = 0;
-    for (const rawLine of lines) {
-        const line = rawLine.trim();
-        if (!line || line.startsWith("#")) {
-            continue;
-        }
-        const classMatch = /^(.+?)\s+->\s+(.+):$/.exec(line);
-        if (classMatch) {
-            const mojangClass = classMatch[1]?.trim() ?? "";
-            const obfuscatedClass = classMatch[2]?.trim() ?? "";
-            if (mojangClass && obfuscatedClass) {
-                mojangToObfuscatedClass.set(mojangClass, obfuscatedClass);
-                classCount += 1;
-            }
-        }
-    }
-    if (classCount === 0) {
-        throw createError({
-            code: ERROR_CODES.MAPPING_UNAVAILABLE,
-            message: "No class mappings could be parsed from client mappings."
-        });
-    }
-    // Pass 2: build full index with descriptors
-    let currentClass;
-    for (const rawLine of lines) {
-        const line = rawLine.trim();
-        if (!line || line.startsWith("#")) {
-            continue;
-        }
-        const classMatch = /^(.+?)\s+->\s+(.+):$/.exec(line);
-        if (classMatch) {
-            const mojangClass = classMatch[1]?.trim() ?? "";
-            const obfuscatedClass = classMatch[2]?.trim() ?? "";
-            if (!mojangClass || !obfuscatedClass) {
-                currentClass = undefined;
-                continue;
-            }
-            currentClass = {
-                obfuscated: obfuscatedClass,
-                mojang: mojangClass
-            };
-            addLookupEntries(obfuscatedToMojang, createClassSymbolRecord(obfuscatedClass), createClassSymbolRecord(mojangClass));
-            addLookupEntries(mojangToObfuscated, createClassSymbolRecord(mojangClass), createClassSymbolRecord(obfuscatedClass));
-            continue;
-        }
-        if (!currentClass) {
-            continue;
-        }
-        const arrowIndex = line.indexOf(" -> ");
-        if (arrowIndex < 0) {
-            continue;
-        }
-        const leftRaw = line.slice(0, arrowIndex).trim();
-        const rightRaw = line.slice(arrowIndex + 4).trim();
-        if (!leftRaw || !rightRaw) {
-            continue;
-        }
-        const mojangMemberSignature = stripLineInfo(leftRaw);
-        // Try method parsing with JVM descriptor
-        const obfuscatedMethod = parseProguardMethod(mojangMemberSignature, mojangToObfuscatedClass);
-        if (obfuscatedMethod) {
-            const mojangMethod = parseProguardMethod(mojangMemberSignature, undefined);
-            const obfuscatedDescriptor = obfuscatedMethod.descriptor;
-            const mojangDescriptor = mojangMethod?.descriptor;
-            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(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("obfuscated", "mojang"), obfuscatedToMojang);
-    result.set(pairKey("mojang", "obfuscated"), mojangToObfuscated);
-    return result;
-}
-function normalizeTinyNamespace(namespace) {
-    const normalized = namespace.trim().toLowerCase();
-    if (normalized === "obfuscated" || normalized === "official") {
-        return "obfuscated";
-    }
-    if (normalized === "mojang") {
-        return "mojang";
-    }
-    if (normalized === "intermediary") {
-        return "intermediary";
-    }
-    if (normalized === "named" || normalized === "yarn") {
-        return "yarn";
-    }
-    return undefined;
-}
-function addPairRecords(target, records) {
-    for (const [sourceMapping, sourceRecord] of records.entries()) {
-        for (const [targetMapping, targetRecord] of records.entries()) {
-            if (sourceMapping === targetMapping) {
-                continue;
-            }
-            addLookupEntries(ensurePairIndex(target, sourceMapping, targetMapping), sourceRecord, targetRecord);
-        }
-    }
-}
-function parseTinyMappings(text) {
-    const lines = text.split(/\r?\n/).filter((line) => line.trim().length > 0);
-    if (lines.length === 0) {
-        return new Map();
-    }
-    const header = lines[0].split("\t");
-    if (header.length < 5 || header[0] !== "tiny" || header[1] !== "2") {
-        return new Map();
-    }
-    const namespaceColumns = header.slice(3).map((namespace, index) => ({
-        mapping: normalizeTinyNamespace(namespace),
-        columnIndex: index + 1
-    }));
-    const recognized = namespaceColumns.filter((entry) => entry.mapping != null);
-    if (recognized.length < 2) {
-        return new Map();
-    }
-    const result = new Map();
-    const currentClassNames = new Map();
-    for (const line of lines.slice(1)) {
-        const columns = line.split("\t");
-        if (columns[0] === "c") {
-            const classRecords = new Map();
-            for (const namespace of recognized) {
-                const value = columns[namespace.columnIndex]?.trim() ?? "";
-                if (!value) {
-                    continue;
-                }
-                currentClassNames.set(namespace.mapping, value);
-                classRecords.set(namespace.mapping, createClassSymbolRecord(value));
-            }
-            addPairRecords(result, classRecords);
-            continue;
-        }
-        if (columns[0] === "" && columns[1] === "f") {
-            const fieldRecords = new Map();
-            for (const namespace of recognized) {
-                const owner = currentClassNames.get(namespace.mapping);
-                const value = columns[namespace.columnIndex + 2]?.trim() ?? "";
-                if (!owner || !value) {
-                    continue;
-                }
-                fieldRecords.set(namespace.mapping, createFieldSymbolRecord(owner, value));
-            }
-            addPairRecords(result, fieldRecords);
-            continue;
-        }
-        if (columns[0] === "" && columns[1] === "m") {
-            const descriptor = columns[2]?.trim() || undefined;
-            const methodRecords = new Map();
-            for (const namespace of recognized) {
-                const owner = currentClassNames.get(namespace.mapping);
-                const value = columns[namespace.columnIndex + 2]?.trim() ?? "";
-                if (!owner || !value) {
-                    continue;
-                }
-                methodRecords.set(namespace.mapping, createMethodSymbolRecord(owner, value, descriptor));
-            }
-            addPairRecords(result, methodRecords);
-        }
-    }
-    return result;
-}
-function addCandidates(target, index, symbols, kind, confidence) {
-    if (!symbols || symbols.size === 0) {
-        return;
-    }
-    const rank = MATCH_RANK[kind];
-    for (const key of symbols) {
-        const record = index.records.get(key);
-        if (!record) {
-            continue;
-        }
-        const current = target.get(key);
-        if (!current || rank > current.rank || (rank === current.rank && confidence > current.confidence)) {
-            target.set(key, {
-                key,
-                record,
-                matchKind: kind,
-                confidence,
-                rank
-            });
-        }
-    }
-}
-function lookupCandidates(index, query) {
-    const trimmedQuery = query.symbol.trim();
-    const collected = new Map();
-    addCandidates(collected, index, index.exact.get(trimmedQuery), "exact", 1);
-    for (const variant of normalizedVariants(trimmedQuery)) {
-        addCandidates(collected, index, index.normalized.get(variant), "normalized", 0.9);
-    }
-    if (query.kind === "method" && query.owner && query.descriptor) {
-        const descriptorlessKey = `${query.owner}.${query.name}`;
-        addCandidates(collected, index, index.exact.get(descriptorlessKey), "normalized", DESCRIPTOR_FALLBACK_CONFIDENCE);
-        for (const variant of normalizedVariants(descriptorlessKey)) {
-            addCandidates(collected, index, index.normalized.get(variant), "normalized", DESCRIPTOR_FALLBACK_CONFIDENCE);
-        }
-    }
-    const simpleKeys = new Set();
-    const shortName = simpleName(trimmedQuery);
-    if (shortName) {
-        simpleKeys.add(shortName);
-    }
-    if (query.kind !== "class") {
-        simpleKeys.add(query.name);
-    }
-    if (query.kind === "method" && query.descriptor) {
-        simpleKeys.add(`${query.name}${query.descriptor}`);
-    }
-    for (const key of simpleKeys) {
-        addCandidates(collected, index, index.simple.get(key), "simple-name", 0.75);
-    }
-    return [...collected.values()]
-        .sort((left, right) => {
-        if (right.confidence !== left.confidence) {
-            return right.confidence - left.confidence;
-        }
-        if (right.rank !== left.rank) {
-            return right.rank - left.rank;
-        }
-        return left.record.symbol.localeCompare(right.record.symbol);
-    })
-        .slice(0, MAX_CANDIDATES)
-        .map(({ record, matchKind, confidence }) => ({
-        symbol: record.symbol,
-        matchKind,
-        confidence,
-        kind: record.kind,
-        owner: record.owner,
-        name: record.name,
-        descriptor: record.descriptor
-    }));
-}
-function mappingPriorityFromInput(configPriority, override) {
-    if (override === "loom-first" || override === "maven-first") {
-        return override;
-    }
-    return configPriority;
-}
-function mappingSourceOrder(priority) {
-    if (priority === "maven-first") {
-        return ["maven", "loom-cache"];
-    }
-    return ["loom-cache", "maven"];
-}
-function requiresOnlyObfuscatedMojangGraph(sourceMapping, targetMapping) {
-    return sourceMapping !== "intermediary" &&
-        sourceMapping !== "yarn" &&
-        targetMapping !== "intermediary" &&
-        targetMapping !== "yarn";
-}
-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 (queueIndex < queue.length) {
-        const current = queue[queueIndex];
-        queueIndex += 1;
-        if (current === targetMapping) {
-            break;
-        }
-        const neighbors = adjacency.get(current);
-        if (!neighbors) {
-            continue;
-        }
-        for (const neighbor of neighbors) {
-            if (parent.has(neighbor)) {
-                continue;
-            }
-            parent.set(neighbor, current);
-            queue.push(neighbor);
-        }
-    }
-    if (!parent.has(targetMapping)) {
-        graph.pathCache.set(key, undefined);
-        return undefined;
-    }
-    const reversedPath = [];
-    let cursor = targetMapping;
-    while (cursor) {
-        reversedPath.push(cursor);
-        cursor = parent.get(cursor);
-    }
-    const path = reversedPath.reverse();
-    graph.pathCache.set(key, path);
-    return path;
-}
-function pathUsesSource(pairs, path, source) {
-    for (let index = 0; index < path.length - 1; index += 1) {
-        const hop = pairs.get(pairKey(path[index], path[index + 1]));
-        if (hop?.source === source) {
-            return true;
-        }
-    }
-    return false;
-}
-function pathToTransformChain(path) {
-    if (path.length <= 1) {
-        return [];
-    }
-    const transform = [];
-    for (let index = 0; index < path.length - 1; index += 1) {
-        transform.push(`mapping:${path[index]}->${path[index + 1]}`);
-    }
-    return transform;
-}
-function toLookupCandidate(record) {
-    return {
-        symbol: record.symbol,
-        matchKind: "exact",
-        confidence: 1,
-        kind: record.kind,
-        owner: record.owner,
-        name: record.name,
-        descriptor: record.descriptor
-    };
-}
-function toSymbolReference(record) {
-    return {
-        kind: record.kind,
-        name: record.kind === "class" ? record.symbol : record.name,
-        owner: record.kind === "class" ? undefined : record.owner,
-        descriptor: record.kind === "method" ? record.descriptor : undefined,
-        symbol: record.symbol
-    };
-}
-function toResolutionCandidate(candidate) {
-    return {
-        kind: candidate.kind,
-        name: candidate.kind === "class" ? candidate.symbol : candidate.name,
-        owner: candidate.kind === "class" ? undefined : candidate.owner,
-        descriptor: candidate.kind === "method" ? candidate.descriptor : undefined,
-        symbol: candidate.symbol,
-        matchKind: candidate.matchKind,
-        confidence: candidate.confidence
-    };
-}
-function invalidInputError(message, details) {
-    return createError({
-        code: ERROR_CODES.INVALID_INPUT,
-        message,
-        details
-    });
-}
-function normalizeMemberName(name) {
-    const normalized = name.trim();
-    if (!normalized || /[\s./()]/.test(normalized)) {
-        throw invalidInputError("name must be a simple member name without separators when kind is field or method.", {
-            name
-        });
-    }
-    return normalized;
-}
-function normalizeMethodDescriptor(descriptor) {
-    const normalized = descriptor?.trim() ?? "";
-    if (!normalized || !normalized.startsWith("(") || !normalized.includes(")")) {
-        throw invalidInputError("descriptor must be a valid JVM descriptor when kind=method.", {
-            descriptor
-        });
-    }
-    return normalized;
-}
-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".', {
-            kind: input.kind
-        });
-    }
-    const normalizedName = input.name?.trim() ?? "";
-    if (!normalizedName) {
-        throw invalidInputError("name must be a non-empty string.", {
-            name: input.name
-        });
-    }
-    if (input.kind === "class") {
-        const owner = input.owner?.trim();
-        if (owner) {
-            throw invalidInputError("owner is not allowed when kind=class. Use name as FQCN.", {
-                owner: input.owner,
-                nextAction: 'Provide class as name, e.g. "net.minecraft.server.Main".'
-            });
-        }
-        if (input.descriptor?.trim()) {
-            throw invalidInputError("descriptor is not allowed when kind=class.", {
-                descriptor: input.descriptor
-            });
-        }
-        const className = normalizeMappedSymbolOutput(normalizedName);
-        if (!className.includes(".") && !options?.allowShortClassName) {
-            throw invalidInputError("name must be a fully qualified class name when kind=class.", {
-                name: input.name
-            });
-        }
-        const record = createClassSymbolRecord(className);
-        return {
-            record,
-            querySymbol: toSymbolReference(record)
-        };
-    }
-    const owner = normalizeMappedSymbolOutput(input.owner?.trim() ?? "");
-    if (!owner) {
-        throw invalidInputError("owner is required when kind is field or method.", {
-            owner: input.owner,
-            kind: input.kind
-        });
-    }
-    if (input.kind === "field") {
-        if (input.descriptor?.trim()) {
-            throw invalidInputError("descriptor is not allowed when kind=field.", {
-                descriptor: input.descriptor
-            });
-        }
-        const record = createFieldSymbolRecord(owner, normalizeMemberName(normalizedName));
-        return {
-            record,
-            querySymbol: toSymbolReference(record)
-        };
-    }
-    const descriptor = signatureMode === "name-only"
-        ? (input.descriptor?.trim() || "")
-        : normalizeMethodDescriptor(input.descriptor);
-    const record = createMethodSymbolRecord(owner, normalizeMemberName(normalizedName), descriptor);
-    return {
-        record,
-        querySymbol: toSymbolReference(record)
-    };
-}
-function normalizeOwnerHint(ownerHint) {
-    const normalized = ownerHint?.trim();
-    if (!normalized) {
-        return undefined;
-    }
-    return normalizeMappedSymbolOutput(normalized);
-}
-function normalizeDescriptorHint(descriptorHint) {
-    const normalized = descriptorHint?.trim();
-    return normalized || undefined;
-}
-function applyDisambiguationHints(candidates, disambiguation) {
-    if (!disambiguation || candidates.length <= 1) {
-        return candidates;
-    }
-    let filtered = [...candidates];
-    const ownerHint = normalizeOwnerHint(disambiguation.ownerHint);
-    if (ownerHint) {
-        const ownerMatched = filtered.filter((candidate) => {
-            if (candidate.owner) {
-                return normalizeMappedSymbolOutput(candidate.owner) === ownerHint;
-            }
-            const normalizedSymbol = normalizeMappedSymbolOutput(candidate.symbol);
-            return normalizedSymbol.startsWith(`${ownerHint}.`);
-        });
-        if (ownerMatched.length > 0) {
-            filtered = ownerMatched;
-        }
-    }
-    const descriptorHint = normalizeDescriptorHint(disambiguation.descriptorHint);
-    if (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) ?? [])];
-}
-function normalizeIncludedKinds(inputKinds) {
-    const normalized = new Set();
-    const kinds = inputKinds ?? ["class", "field", "method"];
-    for (const kind of kinds) {
-        if (kind === "class" || kind === "field" || kind === "method") {
-            normalized.add(kind);
-        }
-    }
-    if (normalized.size === 0) {
-        normalized.add("class");
-        normalized.add("field");
-        normalized.add("method");
-    }
-    return normalized;
-}
-function inferAmbiguityReasons(candidates, usedMojangClientMappings) {
-    if (candidates.length <= 1) {
-        return [];
-    }
-    const reasons = [];
-    const owners = [...new Set(candidates.map((c) => c.owner).filter(Boolean))];
-    if (owners.length > 1) {
-        reasons.push(`Multiple owner classes matched: ${owners.join(", ")}`);
-    }
-    const matchKinds = [...new Set(candidates.map((c) => c.matchKind))];
-    if (matchKinds.length > 1) {
-        reasons.push(`Candidates matched at different precision levels: ${matchKinds.join(", ")}`);
-    }
-    if (usedMojangClientMappings) {
-        const hasDescriptor = candidates.some((c) => c.descriptor);
-        const missingDescriptor = candidates.some((c) => !c.descriptor);
-        if (hasDescriptor && missingDescriptor) {
-            reasons.push("Method descriptor was lost through mojang-client-mappings path, causing broader matching.");
-        }
-    }
-    if (owners.length <= 1) {
-        const descriptors = [...new Set(candidates.map((c) => c.descriptor).filter(Boolean))];
-        if (descriptors.length > 1) {
-            reasons.push(`Overloaded method: ${descriptors.length} variants`);
-        }
-    }
-    if (reasons.length === 0) {
-        reasons.push(`${candidates.length} candidates matched with similar confidence scores.`);
-    }
-    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)));
-}
+/* parsers extracted to src/mapping/parsers/{symbol-records,normalize,proguard,tiny}.ts */
 export class MappingService {
     config;
     versionService;
     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;
@@ -932,9 +54,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)) {
@@ -992,13 +130,51 @@ export class MappingService {
         const descriptorProjection = queryRecord.kind === "method" && queryRecord.descriptor
             ? this.projectMethodDescriptorToTarget(graph, path, queryRecord.descriptor)
             : undefined;
-        const projectedDescriptor = descriptorProjection?.complete ? descriptorProjection.descriptor : undefined;
-        const rawCandidates = this
+        // 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}.`);
@@ -1016,12 +192,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",
@@ -1034,6 +219,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();
@@ -1078,7 +266,7 @@ export class MappingService {
                     targetMapping,
                     sourcePriority: priority,
                     nextAction: "Try mapping=obfuscated which is always available.",
-                    suggestedCall: { tool: "resolve-artifact", params: { mapping: "obfuscated" } }
+                    ...buildSuggestedCall({ tool: "resolve-artifact", params: { mapping: "obfuscated" } })
                 }
             });
         }
@@ -1193,6 +381,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,
@@ -1495,6 +686,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,
@@ -1537,11 +731,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");
         }
@@ -1865,225 +1088,21 @@ export class MappingService {
         }
     }
     async loadMojangPairs(version) {
-        const warnings = [];
-        let metadata;
-        try {
-            metadata = await this.versionService.resolveVersionMappings(version);
-        }
-        catch (caughtError) {
-            return {
-                pairs: new Map(),
-                warnings: [
-                    `Failed to resolve version metadata for "${version}": ${caughtError instanceof Error ? caughtError.message : String(caughtError)}`
-                ],
-                mappingArtifact: `version:${version}`
-            };
-        }
-        const clientMappingsUrl = metadata.clientMappingsUrl ?? metadata.mappingsUrl;
-        if (!clientMappingsUrl) {
-            warnings.push(`Minecraft version "${version}" does not expose client mappings URL.`);
-            return {
-                pairs: new Map(),
-                warnings,
-                mappingArtifact: metadata.versionDetailUrl
-            };
-        }
-        const mappingsPath = join(this.config.cacheDir, "mappings", version, "client_mappings.txt");
-        if (!existsSync(mappingsPath)) {
-            await mkdir(dirname(mappingsPath), { recursive: true });
-            const downloaded = await downloadToCache(clientMappingsUrl, mappingsPath, {
-                fetchFn: this.fetchFn,
-                retries: this.config.fetchRetries,
-                timeoutMs: this.config.fetchTimeoutMs
-            });
-            if (!downloaded.ok || !downloaded.path) {
-                warnings.push(`Failed to download client mappings from "${clientMappingsUrl}" (status: ${downloaded.statusCode ?? "unknown"}).`);
-                return {
-                    pairs: new Map(),
-                    warnings,
-                    mappingArtifact: clientMappingsUrl
-                };
-            }
-        }
-        try {
-            const content = await readFile(mappingsPath, "utf8");
-            return {
-                pairs: parseClientMappings(content),
-                warnings,
-                mappingArtifact: clientMappingsUrl
-            };
-        }
-        catch (caughtError) {
-            warnings.push(`Failed to parse client mappings for "${version}": ${caughtError instanceof Error ? caughtError.message : String(caughtError)}`);
-            return {
-                pairs: new Map(),
-                warnings,
-                mappingArtifact: clientMappingsUrl
-            };
-        }
+        return loadMojangPairs(this.loaderDeps(), version);
     }
     async loadTinyPairsFromLoom(version, projectPath) {
-        const searchRoots = buildVersionSourceSearchRoots(effectiveLoomSearchProjectPath(projectPath));
-        const merged = new Map();
-        const discoveredPaths = new Set();
-        for (const root of searchRoots) {
-            let discovered = [];
-            const versionRoot = join(root, version);
-            try {
-                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 {
-                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: new Map(),
-            warnings: [`No Loom tiny mapping files matched version "${version}".`],
-            mappingArtifact: "loom-cache:none"
-        };
+        return loadTinyPairsFromLoom(version, projectPath);
     }
     async loadTinyPairsFromMaven(version) {
-        const warnings = [];
-        const merged = new Map();
-        const repos = this.config.sourceRepos;
-        const intermediaryUrls = [];
-        const yarnUrls = [];
-        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`);
-            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];
-        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;
-            }
-            for (const [key, index] of result.value.entries()) {
-                const existing = merged.get(key);
-                if (!existing) {
-                    merged.set(key, index);
-                }
-                else {
-                    mergeDirectionIndexes(existing, index);
-                }
-            }
-        }
-        if (merged.size === 0) {
-            warnings.push(`No Maven tiny mappings could be loaded for "${version}".`);
-        }
+        return loadTinyPairsFromMaven(this.loaderDeps(), version);
+    }
+    loaderDeps() {
         return {
-            pairs: merged,
-            warnings,
-            mappingArtifact: allUrls[0] ?? "maven:none"
+            config: this.config,
+            fetchFn: this.fetchFn,
+            versionService: this.versionService
         };
     }
-    async parseTinyFromJar(jarPath) {
-        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 parsed = parseTinyMappings(entry.content);
-                for (const [key, index] of parsed.entries()) {
-                    const existing = merged.get(key);
-                    if (!existing) {
-                        merged.set(key, index);
-                    }
-                    else {
-                        mergeDirectionIndexes(existing, index);
-                    }
-                }
-            }
-            catch {
-                // skip malformed tiny entries
-            }
-        }
-        return merged;
-    }
-    async fetchYarnCoordinates(repoBase, version) {
-        const metadataUrl = `${repoBase}/net/fabricmc/yarn/maven-metadata.xml`;
-        try {
-            const response = await this.fetchFn(metadataUrl);
-            if (!response.ok) {
-                return [];
-            }
-            const xml = await response.text();
-            const versions = [...xml.matchAll(/<version>([^<]+)<\/version>/g)]
-                .map((match) => match[1]?.trim() ?? "")
-                .filter((value) => value.startsWith(`${version}+build.`));
-            const sorted = versions.sort((left, right) => {
-                const leftBuild = Number.parseInt(left.split("+build.")[1] ?? "0", 10);
-                const rightBuild = Number.parseInt(right.split("+build.")[1] ?? "0", 10);
-                return rightBuild - leftBuild;
-            });
-            if (sorted.length > 0) {
-                return sorted.slice(0, 3);
-            }
-            return [version];
-        }
-        catch {
-            return [version];
-        }
-    }
     trimGraphCache() {
         const maxEntries = Math.max(1, this.config.maxMappingGraphCache ?? 16);
         while (this.graphCache.size > maxEntries) {
@@ -2094,6 +1113,11 @@ 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) {
@@ -2106,6 +1130,42 @@ export class MappingService {
                 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);
+        }
     }
 }
 // ---------------------------------------------------------------------------