@adhisang/minecraft-modding-mcp 1.0.0

package/dist/mapping-service.js

@@ -0,0 +1,1706 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import fastGlob from "fast-glob";
+import { createError, ERROR_CODES } from "./errors.js";
+import { 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",
+    "mojang",
+    "intermediary",
+    "yarn"
+]);
+const MATCH_RANK = {
+    exact: 3,
+    normalized: 2,
+    "simple-name": 1
+};
+const DESCRIPTOR_FALLBACK_CONFIDENCE = 0.85;
+const MAX_CANDIDATES = 200;
+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 = new Set();
+    variants.add(symbol);
+    const dotted = symbol.replace(/\//g, ".");
+    variants.add(dotted);
+    const slashed = symbol.replace(/\./g, "/");
+    variants.add(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 [source, target] = key.split("->");
+    return {
+        sourceMapping: source,
+        targetMapping: target
+    };
+}
+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;
+}
+function parseClientMappings(text) {
+    const officialToMojang = createDirectionIndex();
+    const mojangToOfficial = createDirectionIndex();
+    let classCount = 0;
+    let currentClass;
+    for (const rawLine of text.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#")) {
+            continue;
+        }
+        const classMatch = /^(.+?)\s+->\s+(.+):$/.exec(line);
+        if (classMatch) {
+            const mojangClass = classMatch[1]?.trim() ?? "";
+            const officialClass = classMatch[2]?.trim() ?? "";
+            if (!mojangClass || !officialClass) {
+                currentClass = undefined;
+                continue;
+            }
+            classCount += 1;
+            currentClass = {
+                official: officialClass,
+                mojang: mojangClass
+            };
+            addLookupEntries(officialToMojang, createClassSymbolRecord(officialClass), createClassSymbolRecord(mojangClass));
+            addLookupEntries(mojangToOfficial, createClassSymbolRecord(mojangClass), createClassSymbolRecord(officialClass));
+            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);
+        const methodName = parseMethodName(mojangMemberSignature);
+        if (methodName) {
+            addLookupEntries(officialToMojang, createMethodSymbolRecord(currentClass.official, rightRaw, undefined), createMethodSymbolRecord(currentClass.mojang, methodName, undefined));
+            addLookupEntries(mojangToOfficial, createMethodSymbolRecord(currentClass.mojang, methodName, undefined), createMethodSymbolRecord(currentClass.official, rightRaw, undefined));
+            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));
+    }
+    if (classCount === 0) {
+        throw createError({
+            code: ERROR_CODES.MAPPING_UNAVAILABLE,
+            message: "No class mappings could be parsed from client mappings."
+        });
+    }
+    const result = new Map();
+    result.set(pairKey("official", "mojang"), officialToMojang);
+    result.set(pairKey("mojang", "official"), mojangToOfficial);
+    return result;
+}
+function normalizeTinyNamespace(namespace) {
+    const normalized = namespace.trim().toLowerCase();
+    if (normalized === "official") {
+        return "official";
+    }
+    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 namespacePath(pairs, sourceMapping, targetMapping) {
+    if (sourceMapping === targetMapping) {
+        return [sourceMapping];
+    }
+    const queue = [sourceMapping];
+    const parent = new Map([[sourceMapping, undefined]]);
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (current === targetMapping) {
+            break;
+        }
+        for (const key of pairs.keys()) {
+            const parsed = parsePairKey(key);
+            if (parsed.sourceMapping !== current) {
+                continue;
+            }
+            if (parent.has(parsed.targetMapping)) {
+                continue;
+            }
+            parent.set(parsed.targetMapping, current);
+            queue.push(parsed.targetMapping);
+        }
+    }
+    if (!parent.has(targetMapping)) {
+        return undefined;
+    }
+    const path = [];
+    let cursor = targetMapping;
+    while (cursor) {
+        path.unshift(cursor);
+        cursor = parent.get(cursor);
+    }
+    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) {
+    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(".")) {
+            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 record = createMethodSymbolRecord(owner, normalizeMemberName(normalizedName), normalizeMethodDescriptor(input.descriptor));
+    return {
+        record,
+        querySymbol: toSymbolReference(record)
+    };
+}
+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()];
+}
+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;
+}
+export class MappingService {
+    config;
+    versionService;
+    fetchFn;
+    graphCache = new Map();
+    buildLocks = new Map();
+    constructor(config, versionService = new VersionService(config), fetchFn = globalThis.fetch) {
+        this.config = config;
+        this.versionService = versionService;
+        this.fetchFn = fetchFn;
+    }
+    async findMapping(input) {
+        const version = input.version.trim();
+        if (!version) {
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: "version must be non-empty.",
+                details: {
+                    version: input.version
+                }
+            });
+        }
+        const { record: queryRecord, querySymbol } = normalizeQuerySymbol(input);
+        const sourceMapping = input.sourceMapping;
+        const targetMapping = input.targetMapping;
+        if (!SUPPORTED_MAPPINGS.has(sourceMapping) || !SUPPORTED_MAPPINGS.has(targetMapping)) {
+            throw createError({
+                code: ERROR_CODES.MAPPING_UNAVAILABLE,
+                message: "Unsupported mapping pair for lookup.",
+                details: {
+                    version,
+                    sourceMapping,
+                    targetMapping
+                }
+            });
+        }
+        const priority = mappingPriorityFromInput(this.config.mappingSourcePriority, input.sourcePriority);
+        const mappingContext = {
+            version,
+            sourceMapping,
+            targetMapping,
+            sourcePriorityApplied: priority
+        };
+        if (sourceMapping === targetMapping) {
+            const identity = toResolutionCandidate({
+                ...toLookupCandidate(queryRecord),
+                matchKind: "exact",
+                confidence: 1
+            });
+            return {
+                querySymbol,
+                mappingContext,
+                resolved: true,
+                status: "resolved",
+                resolvedSymbol: querySymbol,
+                candidates: [identity],
+                warnings: []
+            };
+        }
+        const graph = await this.loadGraph(version, priority);
+        const path = namespacePath(graph.pairs, sourceMapping, targetMapping);
+        if (!path) {
+            return {
+                querySymbol,
+                mappingContext,
+                resolved: false,
+                status: "mapping_unavailable",
+                candidates: [],
+                warnings: [
+                    `No mapping path is available for ${sourceMapping} -> ${targetMapping} on version "${version}".`
+                ]
+            };
+        }
+        const rawCandidates = this.mapCandidatesAlongPath(graph, path, queryRecord);
+        const candidates = rawCandidates.map(toResolutionCandidate);
+        const warnings = [];
+        if (queryRecord.kind === "method" &&
+            queryRecord.descriptor &&
+            pathUsesSource(graph.pairs, path, "mojang-client-mappings")) {
+            warnings.push("Method descriptor could not be preserved through mojang-client-mappings and may have used name-based fallback.");
+        }
+        if (candidates.length === 0) {
+            warnings.push("No mapping candidate matched the input symbol.");
+        }
+        const status = candidates.length === 0 ? "not_found" : candidates.length === 1 ? "resolved" : "ambiguous";
+        return {
+            querySymbol,
+            mappingContext,
+            resolved: status === "resolved",
+            status,
+            resolvedSymbol: status === "resolved" ? candidates[0] : undefined,
+            candidates,
+            warnings,
+            provenance: this.provenanceForPath(graph, path)
+        };
+    }
+    async ensureMappingAvailable(input) {
+        const version = input.version.trim();
+        if (!version) {
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: "version must be non-empty.",
+                details: {
+                    version: input.version
+                }
+            });
+        }
+        const sourceMapping = input.sourceMapping;
+        const targetMapping = input.targetMapping;
+        if (!SUPPORTED_MAPPINGS.has(sourceMapping) || !SUPPORTED_MAPPINGS.has(targetMapping)) {
+            throw createError({
+                code: ERROR_CODES.MAPPING_UNAVAILABLE,
+                message: "Unsupported mapping pair.",
+                details: {
+                    version,
+                    sourceMapping,
+                    targetMapping
+                }
+            });
+        }
+        const priority = mappingPriorityFromInput(this.config.mappingSourcePriority, input.sourcePriority);
+        if (sourceMapping === targetMapping) {
+            return {
+                transformChain: [`mapping:${sourceMapping}->${targetMapping}`],
+                warnings: []
+            };
+        }
+        const graph = await this.loadGraph(version, priority);
+        const path = namespacePath(graph.pairs, sourceMapping, targetMapping);
+        if (!path) {
+            throw createError({
+                code: ERROR_CODES.MAPPING_UNAVAILABLE,
+                message: `No mapping path is available for ${sourceMapping} -> ${targetMapping} on version "${version}".`,
+                details: {
+                    version,
+                    sourceMapping,
+                    targetMapping,
+                    sourcePriority: priority
+                }
+            });
+        }
+        const provenance = this.provenanceForPath(graph, path);
+        const transformChain = [
+            provenance ? `mapping-source:${provenance.source}` : undefined,
+            ...pathToTransformChain(path)
+        ].filter((entry) => Boolean(entry));
+        return {
+            transformChain,
+            warnings: [...graph.warnings],
+            provenance
+        };
+    }
+    async resolveMethodMappingExact(input) {
+        const version = input.version.trim();
+        if (!version) {
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: "version must be non-empty.",
+                details: {
+                    version: input.version
+                }
+            });
+        }
+        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 owner = queryRecord.owner;
+        const method = queryRecord.name;
+        const descriptor = queryRecord.descriptor;
+        const sourceMapping = input.sourceMapping;
+        const targetMapping = input.targetMapping;
+        if (!SUPPORTED_MAPPINGS.has(sourceMapping) || !SUPPORTED_MAPPINGS.has(targetMapping)) {
+            throw createError({
+                code: ERROR_CODES.MAPPING_UNAVAILABLE,
+                message: "Unsupported mapping pair for exact method resolution.",
+                details: {
+                    version,
+                    sourceMapping,
+                    targetMapping
+                }
+            });
+        }
+        const priority = mappingPriorityFromInput(this.config.mappingSourcePriority, input.sourcePriority);
+        const mappingContext = {
+            version,
+            sourceMapping,
+            targetMapping,
+            sourcePriorityApplied: priority
+        };
+        if (sourceMapping === targetMapping) {
+            const resolvedCandidate = toResolutionCandidate({
+                ...toLookupCandidate(queryRecord),
+                matchKind: "exact",
+                confidence: 1
+            });
+            return {
+                querySymbol,
+                mappingContext,
+                resolved: true,
+                status: "resolved",
+                resolvedSymbol: resolvedCandidate,
+                candidates: [resolvedCandidate],
+                warnings: []
+            };
+        }
+        const graph = await this.loadGraph(version, priority);
+        const path = namespacePath(graph.pairs, sourceMapping, targetMapping);
+        if (!path) {
+            return {
+                querySymbol,
+                mappingContext,
+                resolved: false,
+                status: "mapping_unavailable",
+                candidates: [],
+                warnings: [
+                    `No mapping path is available for ${sourceMapping} -> ${targetMapping} on version "${version}".`
+                ]
+            };
+        }
+        const warnings = [];
+        const rawCandidates = this
+            .mapCandidatesAlongPath(graph, path, queryRecord)
+            .filter((candidate) => candidate.kind === "method");
+        const candidates = rawCandidates.map(toResolutionCandidate);
+        const strictCandidates = rawCandidates.filter((candidate) => candidate.descriptor === descriptor);
+        if (strictCandidates.length === 1) {
+            const resolved = toResolutionCandidate(strictCandidates[0]);
+            return {
+                querySymbol,
+                mappingContext,
+                resolved: true,
+                status: "resolved",
+                resolvedSymbol: resolved,
+                candidates,
+                warnings,
+                provenance: this.provenanceForPath(graph, path)
+            };
+        }
+        if (strictCandidates.length > 1) {
+            warnings.push("Exact method mapping is ambiguous for owner+method+descriptor.");
+            return {
+                querySymbol,
+                mappingContext,
+                resolved: false,
+                status: "ambiguous",
+                candidates,
+                warnings,
+                provenance: this.provenanceForPath(graph, path)
+            };
+        }
+        if (pathUsesSource(graph.pairs, path, "mojang-client-mappings")) {
+            warnings.push("Method descriptor could not be preserved through mojang-client-mappings and exact resolution is unavailable.");
+            return {
+                querySymbol,
+                mappingContext,
+                resolved: false,
+                status: "mapping_unavailable",
+                candidates,
+                warnings,
+                provenance: this.provenanceForPath(graph, path)
+            };
+        }
+        return {
+            querySymbol,
+            mappingContext,
+            resolved: false,
+            status: "not_found",
+            candidates,
+            warnings,
+            provenance: this.provenanceForPath(graph, path)
+        };
+    }
+    async getClassApiMatrix(input) {
+        const version = input.version.trim();
+        const className = normalizeMappedSymbolOutput(input.className.trim());
+        if (!version || !className) {
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: "version and className must be non-empty strings.",
+                details: {
+                    version: input.version,
+                    className: input.className
+                }
+            });
+        }
+        const classNameMapping = input.classNameMapping;
+        if (!SUPPORTED_MAPPINGS.has(classNameMapping)) {
+            throw createError({
+                code: ERROR_CODES.MAPPING_UNAVAILABLE,
+                message: "Unsupported classNameMapping.",
+                details: {
+                    classNameMapping
+                }
+            });
+        }
+        const priority = mappingPriorityFromInput(this.config.mappingSourcePriority, input.sourcePriority);
+        const graph = await this.loadGraph(version, priority);
+        const warnings = [...graph.warnings];
+        const includeKinds = normalizeIncludedKinds(input.includeKinds);
+        const classByMapping = {
+            [classNameMapping]: createClassSymbolRecord(className)
+        };
+        for (const mapping of SUPPORTED_MAPPINGS) {
+            if (mapping === classNameMapping) {
+                continue;
+            }
+            const mapped = this.mapRecordBetweenMappings(graph, classNameMapping, mapping, classByMapping[classNameMapping]);
+            if (mapped.length > 1) {
+                warnings.push(`Class identity mapping to ${mapping} is ambiguous for "${className}".`);
+            }
+            if (mapped.length > 0) {
+                classByMapping[mapping] = mapped[0];
+            }
+        }
+        const baseMapping = classByMapping.official ? "official" : classNameMapping;
+        const baseClass = classByMapping[baseMapping];
+        if (!baseClass) {
+            return {
+                version,
+                className,
+                classNameMapping,
+                classIdentity: {
+                    official: classByMapping.official?.symbol,
+                    mojang: classByMapping.mojang?.symbol,
+                    intermediary: classByMapping.intermediary?.symbol,
+                    yarn: classByMapping.yarn?.symbol
+                },
+                rows: [],
+                warnings
+            };
+        }
+        const baseRecords = collectTargetRecords(graph, baseMapping).filter((record) => {
+            if (record.kind === "class") {
+                return includeKinds.has("class") && record.symbol === baseClass.symbol;
+            }
+            if (record.owner !== baseClass.symbol) {
+                return false;
+            }
+            if (record.kind === "field") {
+                return includeKinds.has("field");
+            }
+            return includeKinds.has("method");
+        });
+        const rows = [];
+        const rowSeen = new Set();
+        const rowKindOrder = {
+            class: 0,
+            field: 1,
+            method: 2
+        };
+        const sortedBase = [...baseRecords].sort((left, right) => {
+            const leftKind = rowKindOrder[left.kind];
+            const rightKind = rowKindOrder[right.kind];
+            if (leftKind !== rightKind) {
+                return leftKind - rightKind;
+            }
+            if ((left.descriptor ?? "") !== (right.descriptor ?? "")) {
+                return (left.descriptor ?? "").localeCompare(right.descriptor ?? "");
+            }
+            return left.symbol.localeCompare(right.symbol);
+        });
+        for (const baseRecord of sortedBase) {
+            const key = buildSymbolKey(baseRecord);
+            if (rowSeen.has(key)) {
+                continue;
+            }
+            rowSeen.add(key);
+            const row = {
+                kind: baseRecord.kind,
+                descriptor: baseRecord.descriptor,
+                completeness: false
+            };
+            for (const mapping of SUPPORTED_MAPPINGS) {
+                const classIdentity = classByMapping[mapping];
+                let resolved;
+                if (mapping === baseMapping) {
+                    resolved = baseRecord;
+                }
+                else {
+                    const mapped = this.mapRecordBetweenMappings(graph, baseMapping, mapping, baseRecord);
+                    let filtered = mapped;
+                    if (baseRecord.kind !== "class" && classIdentity) {
+                        filtered = filtered.filter((candidate) => candidate.owner === classIdentity.symbol);
+                    }
+                    if (baseRecord.kind === "method" && baseRecord.descriptor) {
+                        const descriptorMatched = filtered.filter((candidate) => candidate.descriptor === baseRecord.descriptor);
+                        if (descriptorMatched.length > 0) {
+                            filtered = descriptorMatched;
+                        }
+                    }
+                    if (filtered.length > 1) {
+                        warnings.push(`Row mapping to ${mapping} is ambiguous for "${baseRecord.symbol}". Using highest-ranked candidate.`);
+                    }
+                    resolved = filtered[0];
+                }
+                if (!resolved) {
+                    continue;
+                }
+                const entry = {
+                    symbol: resolved.symbol,
+                    owner: resolved.owner,
+                    name: resolved.name,
+                    descriptor: resolved.descriptor
+                };
+                row[mapping] = entry;
+            }
+            row.completeness = Boolean(row.official && row.mojang && row.intermediary && row.yarn);
+            rows.push(row);
+        }
+        return {
+            version,
+            className,
+            classNameMapping,
+            classIdentity: {
+                official: classByMapping.official?.symbol,
+                mojang: classByMapping.mojang?.symbol,
+                intermediary: classByMapping.intermediary?.symbol,
+                yarn: classByMapping.yarn?.symbol
+            },
+            rows,
+            warnings
+        };
+    }
+    async checkSymbolExists(input) {
+        const version = input.version.trim();
+        if (!version) {
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: "version must be non-empty.",
+                details: {
+                    version: input.version
+                }
+            });
+        }
+        const { record: queryRecord, querySymbol } = normalizeQuerySymbol(input);
+        const sourceMapping = input.sourceMapping;
+        if (!SUPPORTED_MAPPINGS.has(sourceMapping)) {
+            throw createError({
+                code: ERROR_CODES.MAPPING_UNAVAILABLE,
+                message: "Unsupported mapping namespace for existence check.",
+                details: {
+                    sourceMapping
+                }
+            });
+        }
+        const priority = mappingPriorityFromInput(this.config.mappingSourcePriority, input.sourcePriority);
+        const mappingContext = {
+            version,
+            sourceMapping,
+            sourcePriorityApplied: priority
+        };
+        const graph = await this.loadGraph(version, priority);
+        const warnings = [...graph.warnings];
+        const records = collectTargetRecords(graph, sourceMapping);
+        if (records.length === 0) {
+            return {
+                querySymbol,
+                mappingContext,
+                resolved: false,
+                status: "mapping_unavailable",
+                candidates: [],
+                warnings
+            };
+        }
+        const buildOutput = (matched, status) => {
+            const candidates = matched.map((record) => toResolutionCandidate(toLookupCandidate(record)));
+            return {
+                querySymbol,
+                mappingContext,
+                resolved: status === "resolved",
+                status,
+                resolvedSymbol: status === "resolved" ? candidates[0] : undefined,
+                candidates,
+                warnings
+            };
+        };
+        if (queryRecord.kind === "class") {
+            const matched = records.filter((record) => record.kind === "class" && record.symbol === queryRecord.symbol);
+            const status = matched.length === 1 ? "resolved" : matched.length > 1 ? "ambiguous" : "not_found";
+            return buildOutput(matched, status);
+        }
+        if (queryRecord.kind === "field") {
+            const matched = records.filter((record) => record.kind === "field" && record.owner === queryRecord.owner && record.name === queryRecord.name);
+            const status = matched.length === 1 ? "resolved" : matched.length > 1 ? "ambiguous" : "not_found";
+            return buildOutput(matched, status);
+        }
+        const methodCandidates = records.filter((record) => record.kind === "method" && record.owner === queryRecord.owner && record.name === queryRecord.name);
+        const descriptorMatched = methodCandidates.filter((record) => record.descriptor === queryRecord.descriptor);
+        if (descriptorMatched.length === 1) {
+            return buildOutput(descriptorMatched, "resolved");
+        }
+        if (descriptorMatched.length > 1) {
+            return buildOutput(descriptorMatched, "ambiguous");
+        }
+        if (methodCandidates.some((candidate) => candidate.descriptor == null)) {
+            warnings.push("Descriptor-level existence checks are unavailable for descriptorless mapping entries.");
+            return buildOutput(methodCandidates, "mapping_unavailable");
+        }
+        return buildOutput([], "not_found");
+    }
+    mapRecordBetweenMappings(graph, sourceMapping, targetMapping, record) {
+        if (sourceMapping === targetMapping) {
+            return [record];
+        }
+        const path = namespacePath(graph.pairs, sourceMapping, targetMapping);
+        if (!path) {
+            return [];
+        }
+        let mapped = this
+            .mapCandidatesAlongPath(graph, path, record)
+            .filter((candidate) => candidate.kind === record.kind)
+            .map((candidate) => ({
+            kind: candidate.kind,
+            symbol: candidate.symbol,
+            owner: candidate.owner,
+            name: candidate.name,
+            descriptor: candidate.descriptor
+        }));
+        if (record.kind === "method" && record.descriptor) {
+            const descriptorMatched = mapped.filter((candidate) => candidate.descriptor === record.descriptor);
+            if (descriptorMatched.length > 0) {
+                mapped = descriptorMatched;
+            }
+        }
+        const deduped = new Map();
+        for (const candidate of mapped) {
+            deduped.set(buildSymbolKey(candidate), candidate);
+        }
+        return [...deduped.values()];
+    }
+    mapCandidatesAlongPath(graph, path, query) {
+        const queryKey = buildSymbolKey(query);
+        let current = new Map([
+            [
+                queryKey,
+                {
+                    key: queryKey,
+                    record: query,
+                    matchKind: "exact",
+                    confidence: 1,
+                    rank: MATCH_RANK.exact
+                }
+            ]
+        ]);
+        for (let index = 0; index < path.length - 1; index += 1) {
+            const from = path[index];
+            const to = path[index + 1];
+            const record = graph.pairs.get(pairKey(from, to));
+            if (!record) {
+                return [];
+            }
+            const next = new Map();
+            for (const candidate of current.values()) {
+                const mapped = lookupCandidates(record.index, candidate.record);
+                for (const item of mapped) {
+                    const mappedRecord = {
+                        kind: item.kind,
+                        symbol: item.symbol,
+                        owner: item.owner,
+                        name: item.name,
+                        descriptor: item.descriptor
+                    };
+                    const mappedKey = buildSymbolKey(mappedRecord);
+                    const rank = MATCH_RANK[item.matchKind];
+                    const composedConfidence = candidate.confidence * item.confidence;
+                    const existing = next.get(mappedKey);
+                    if (!existing ||
+                        composedConfidence > existing.confidence ||
+                        (composedConfidence === existing.confidence && rank > existing.rank)) {
+                        next.set(mappedKey, {
+                            key: mappedKey,
+                            record: mappedRecord,
+                            matchKind: item.matchKind,
+                            confidence: composedConfidence,
+                            rank
+                        });
+                    }
+                }
+            }
+            current = next;
+            if (current.size === 0) {
+                return [];
+            }
+        }
+        return [...current.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((item) => ({
+            symbol: item.record.symbol,
+            matchKind: item.matchKind,
+            confidence: Number(item.confidence.toFixed(6)),
+            kind: item.record.kind,
+            owner: item.record.owner,
+            name: item.record.name,
+            descriptor: item.record.descriptor
+        }));
+    }
+    provenanceForPath(graph, path) {
+        if (path.length <= 1) {
+            return undefined;
+        }
+        const first = graph.pairs.get(pairKey(path[0], path[1]));
+        if (!first) {
+            return undefined;
+        }
+        return {
+            source: first.source,
+            mappingArtifact: first.mappingArtifact,
+            version: graph.version,
+            priority: graph.priority
+        };
+    }
+    async loadGraph(version, priority) {
+        const cacheKey = `${version}|${priority}`;
+        const cached = this.graphCache.get(cacheKey);
+        if (cached) {
+            this.graphCache.delete(cacheKey);
+            this.graphCache.set(cacheKey, cached);
+            return cached;
+        }
+        const existingLock = this.buildLocks.get(cacheKey);
+        if (existingLock) {
+            return existingLock;
+        }
+        const buildPromise = this.buildGraph(version, priority);
+        this.buildLocks.set(cacheKey, buildPromise);
+        try {
+            const built = await buildPromise;
+            this.graphCache.set(cacheKey, built);
+            this.trimGraphCache();
+            return built;
+        }
+        finally {
+            this.buildLocks.delete(cacheKey);
+        }
+    }
+    async buildGraph(version, priority) {
+        if (isUnobfuscatedVersion(version)) {
+            return {
+                version,
+                priority,
+                pairs: new Map(),
+                warnings: [
+                    `Version ${version} is unobfuscated; mapping graph is empty (official names are final).`
+                ]
+            };
+        }
+        const graph = {
+            version,
+            priority,
+            pairs: 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;
+        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) {
+                continue;
+            }
+            tinyLoaded = true;
+            this.mergePairs(graph.pairs, tinyLoad.pairs, source, tinyLoad.mappingArtifact);
+            break;
+        }
+        if (!tinyLoaded) {
+            graph.warnings.push("No intermediary/yarn tiny mappings were found for this version.");
+        }
+        return graph;
+    }
+    mergePairs(target, source, pairSource, mappingArtifact) {
+        for (const [key, incoming] of source.entries()) {
+            const existing = target.get(key);
+            if (!existing) {
+                target.set(key, {
+                    index: incoming,
+                    source: pairSource,
+                    mappingArtifact
+                });
+                continue;
+            }
+            if (existing.source !== pairSource) {
+                continue;
+            }
+            mergeDirectionIndexes(existing.index, incoming);
+        }
+    }
+    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
+            };
+        }
+    }
+    async loadTinyPairsFromLoom(version) {
+        const patterns = [".gradle/loom-cache/**/*.tiny", ".gradle/loom-cache/**/*.tinyv2"];
+        const candidates = fastGlob.sync(patterns, {
+            cwd: process.cwd(),
+            absolute: true,
+            onlyFiles: true
+        });
+        const byVersion = candidates
+            .filter((p) => p.replaceAll("\\", "/").includes(`/${version}/`))
+            .sort((left, right) => left.localeCompare(right));
+        if (byVersion.length === 0) {
+            return {
+                pairs: new Map(),
+                warnings: [`No Loom tiny mapping files matched version "${version}".`],
+                mappingArtifact: "loom-cache:none"
+            };
+        }
+        const merged = new Map();
+        for (const path of byVersion) {
+            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
+            }
+        }
+        return {
+            pairs: merged,
+            warnings: [],
+            mappingArtifact: byVersion[0]
+        };
+    }
+    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(/\/+$/, "");
+            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 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) {
+                continue;
+            }
+            const parsed = await this.parseTinyFromJar(downloaded.path);
+            for (const [key, index] of parsed.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 {
+            pairs: merged,
+            warnings,
+            mappingArtifact: attemptedArtifacts[0] ?? "maven:none"
+        };
+    }
+    async parseTinyFromJar(jarPath) {
+        const entries = await listJarEntries(jarPath);
+        const tinyEntries = entries
+            .filter((entry) => entry.toLowerCase().endsWith(".tiny") || entry.toLowerCase().endsWith(".tinyv2"))
+            .sort((left, right) => left.localeCompare(right));
+        const merged = new Map();
+        for (const entry of tinyEntries) {
+            try {
+                const text = await readJarEntryAsUtf8(jarPath, entry);
+                const parsed = parseTinyMappings(text);
+                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) {
+            const oldestKey = this.graphCache.keys().next().value;
+            if (!oldestKey) {
+                return;
+            }
+            this.graphCache.delete(oldestKey);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Standalone: Tiny v2 mapping file resolution for remapping
+// ---------------------------------------------------------------------------
+const FABRIC_MAVEN = "https://maven.fabricmc.net";
+async function fetchYarnCoordinatesStandalone(version, fetchFn = globalThis.fetch) {
+    const metadataUrl = `${FABRIC_MAVEN}/net/fabricmc/yarn/maven-metadata.xml`;
+    try {
+        const response = await 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;
+        });
+        return sorted.length > 0 ? sorted.slice(0, 3) : [];
+    }
+    catch {
+        return [];
+    }
+}
+async function extractTinyFromJar(jarPath, outputPath) {
+    const entries = await listJarEntries(jarPath);
+    const tinyEntry = entries.find((entry) => entry === "mappings/mappings.tiny" || entry.toLowerCase().endsWith(".tiny"));
+    if (!tinyEntry) {
+        return false;
+    }
+    const content = await readJarEntryAsUtf8(jarPath, tinyEntry);
+    await mkdir(dirname(outputPath), { recursive: true });
+    await writeFile(outputPath, content, "utf8");
+    return true;
+}
+/**
+ * Resolve and cache a Tiny v2 mapping file for the given Minecraft version.
+ *
+ * @param version - Minecraft version (e.g. "1.20.4")
+ * @param mapping - "intermediary" or "yarn"
+ * @param cacheDir - The application cache directory
+ * @param fetchFn - Optional fetch implementation for testing
+ * @returns Path to the extracted Tiny v2 file
+ */
+export async function resolveTinyMappingFile(version, mapping, cacheDir, fetchFn) {
+    const cachedTiny = join(cacheDir, "mappings", `${version}-${mapping}.tiny`);
+    if (existsSync(cachedTiny)) {
+        return cachedTiny;
+    }
+    const effectiveFetch = fetchFn ?? globalThis.fetch;
+    if (mapping === "intermediary") {
+        const url = `${FABRIC_MAVEN}/net/fabricmc/intermediary/${version}/intermediary-${version}-v2.jar`;
+        const jarDest = defaultDownloadPath(cacheDir, url);
+        const downloaded = await downloadToCache(url, jarDest, {
+            fetchFn: effectiveFetch,
+            retries: 2,
+            timeoutMs: 30_000
+        });
+        if (!downloaded.ok || !downloaded.path) {
+            throw createError({
+                code: ERROR_CODES.MAPPING_UNAVAILABLE,
+                message: `Failed to download intermediary mappings for ${version}.`,
+                details: { version, url }
+            });
+        }
+        const extracted = await extractTinyFromJar(downloaded.path, cachedTiny);
+        if (!extracted) {
+            throw createError({
+                code: ERROR_CODES.MAPPING_UNAVAILABLE,
+                message: `No tiny mapping found in intermediary JAR for ${version}.`,
+                details: { version, jarPath: downloaded.path }
+            });
+        }
+        return cachedTiny;
+    }
+    // yarn
+    const yarnCoordinates = await fetchYarnCoordinatesStandalone(version, effectiveFetch);
+    if (yarnCoordinates.length === 0) {
+        throw createError({
+            code: ERROR_CODES.MAPPING_UNAVAILABLE,
+            message: `No yarn builds found for Minecraft ${version}.`,
+            details: { version }
+        });
+    }
+    for (const coordinate of yarnCoordinates) {
+        const url = `${FABRIC_MAVEN}/net/fabricmc/yarn/${coordinate}/yarn-${coordinate}-v2.jar`;
+        const jarDest = defaultDownloadPath(cacheDir, url);
+        const downloaded = await downloadToCache(url, jarDest, {
+            fetchFn: effectiveFetch,
+            retries: 2,
+            timeoutMs: 30_000
+        });
+        if (!downloaded.ok || !downloaded.path) {
+            continue;
+        }
+        const extracted = await extractTinyFromJar(downloaded.path, cachedTiny);
+        if (extracted) {
+            return cachedTiny;
+        }
+    }
+    throw createError({
+        code: ERROR_CODES.MAPPING_UNAVAILABLE,
+        message: `Failed to download yarn mappings for ${version}.`,
+        details: { version, triedCoordinates: yarnCoordinates }
+    });
+}
+//# sourceMappingURL=mapping-service.js.map