@adhisang/minecraft-modding-mcp 4.2.1 → 6.0.0

package/dist/mapping-service.js

@@ -1,8 +1,10 @@
-import { existsSync } from "node:fs";
-import { mkdir, writeFile } from "node:fs/promises";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdir, rename, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
+import { randomBytes } from "node:crypto";
 import { buildSuggestedCall } from "./build-suggested-call.js";
 import { createError, ERROR_CODES } from "./errors.js";
+import { buildPageContextKey, encodeOffsetCursor, resolveCursorOffset } from "./page-cursor.js";
 import { resolveGradleUserHomePath } from "./gradle-paths.js";
 import { defaultDownloadPath, downloadToCache } from "./repo-downloader.js";
 import { collectMatchedJarEntriesAsUtf8 } from "./source-jar-reader.js";
@@ -10,7 +12,7 @@ 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 { applyDisambiguationHints, clampRowLimit, collectExactRecordIndex, collectTargetRecords, effectiveLoomSearchProjectPath, inferAmbiguityReasons, invalidInputError, limitResolutionCandidates, lookupCandidates, lookupExactClassBySimpleName, lookupExactClassBySymbol, lookupExactMembers, lookupExactMembersByOwner, 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";
@@ -32,6 +34,8 @@ export class MappingService {
     static RESOLUTION_CACHE_TTL_MS = 5 * 60 * 1000;
     resolutionCacheHits = 0;
     resolutionCacheMisses = 0;
+    classProjectionComputes = 0;
+    apiMatrixRowMaps = 0;
     get resolutionCacheStats() {
         return {
             hits: this.resolutionCacheHits,
@@ -39,6 +43,14 @@ export class MappingService {
             size: this.resolutionCache.size
         };
     }
+    /** Test seam: counts genuine class-projection computes (cache misses). */
+    get classProjectionStats() {
+        return { computes: this.classProjectionComputes };
+    }
+    /** Test seam: counts genuine per-row cross-namespace path walks in getClassApiMatrix. */
+    get apiMatrixStats() {
+        return { rowMaps: this.apiMatrixRowMaps };
+    }
     constructor(config, versionService = new VersionService(config), fetchFn = globalThis.fetch) {
         this.config = config;
         this.versionService = versionService;
@@ -65,7 +77,7 @@ export class MappingService {
         // explicitly.
         const effectiveSignatureMode = input.signatureMode ?? "name-only";
         const { record: queryRecord, querySymbol } = normalizeQuerySymbol(input, effectiveSignatureMode, {
-            allowShortClassName: input.kind === "class" && input.sourceMapping === "obfuscated"
+            allowShortClassName: input.kind === "class" && (input.sourceMapping === "obfuscated" || input.nameMode === "auto")
         });
         const cacheKey = this.buildResolutionCacheKey(version, input, querySymbol, effectiveSignatureMode);
         const cached = this.resolutionCache.get(cacheKey);
@@ -176,7 +188,7 @@ export class MappingService {
             }
             rawCandidates = rawCandidates.filter((candidate) => candidate.descriptor !== undefined && acceptedDescriptors.has(candidate.descriptor));
         }
-        const disambiguatedCandidates = applyDisambiguationHints(rawCandidates, input.disambiguation);
+        const disambiguatedCandidates = applyDisambiguationHints(rawCandidates, input.disambiguation, warnings);
         if (rawCandidates.length > disambiguatedCandidates.length) {
             warnings.push(`Disambiguation hints narrowed candidates from ${rawCandidates.length} to ${disambiguatedCandidates.length}.`);
         }
@@ -364,7 +376,13 @@ export class MappingService {
         const candidates = rawCandidates.map(toResolutionCandidate);
         const limitedCandidates = limitResolutionCandidates(candidates, input.maxCandidates);
         const strictDescriptor = projectedDescriptor ?? descriptor;
-        const strictCandidates = rawCandidates.filter((candidate) => candidate.descriptor === strictDescriptor);
+        const acceptedDescriptors = new Set([descriptor, strictDescriptor]);
+        const toObfuscatedPath = namespacePath(graph, sourceMapping, "obfuscated");
+        if (toObfuscatedPath) {
+            const obfuscatedProjection = this.projectMethodDescriptorToTarget(graph, toObfuscatedPath, descriptor);
+            acceptedDescriptors.add(obfuscatedProjection.descriptor);
+        }
+        const strictCandidates = rawCandidates.filter((candidate) => candidate.descriptor !== undefined && acceptedDescriptors.has(candidate.descriptor));
         if (strictCandidates.length === 1) {
             const resolved = toResolutionCandidate(strictCandidates[0]);
             return {
@@ -499,21 +517,18 @@ export class MappingService {
                 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;
+        const exactIndex = collectExactRecordIndex(graph, baseMapping);
+        const baseRecords = [];
+        if (includeKinds.has("class")) {
+            for (const record of lookupExactClassBySymbol(exactIndex, baseClass.symbol)) {
+                baseRecords.push(record);
             }
-            if (record.kind === "field") {
-                return includeKinds.has("field");
+        }
+        for (const record of lookupExactMembersByOwner(exactIndex, baseClass.symbol)) {
+            if (record.kind === "field" ? includeKinds.has("field") : includeKinds.has("method")) {
+                baseRecords.push(record);
             }
-            return includeKinds.has("method");
-        });
-        const rows = [];
-        let ambiguousRowCount = 0;
-        const rowSeen = new Set();
+        }
         const rowKindOrder = {
             class: 0,
             field: 1,
@@ -530,12 +545,47 @@ export class MappingService {
             }
             return left.symbol.localeCompare(right.symbol);
         });
+        // Dedup up front using the base-only symbol key. The sort key and buildSymbolKey
+        // read only base-namespace fields, so this stable first-occurrence-wins order is
+        // fully determined WITHOUT any cross-namespace mapping. That lets rowCount /
+        // nextCursor / row order stay byte-identical while we map only the requested page.
+        const rowSeen = new Set();
+        const dedupedBase = [];
         for (const baseRecord of sortedBase) {
             const key = buildSymbolKey(baseRecord);
             if (rowSeen.has(key)) {
                 continue;
             }
             rowSeen.add(key);
+            dedupedBase.push(baseRecord);
+        }
+        const rowCount = dedupedBase.length;
+        const rowLimit = clampRowLimit(input.maxRows);
+        if (input.maxRows != null && Number.isFinite(input.maxRows) && input.maxRows > 5000) {
+            warnings.push(`maxRows was clamped to 5000 from ${input.maxRows}.`);
+        }
+        // Offset cursor over the stable row order; the context key ties a cursor to
+        // this exact query so a stale cursor restarts from the first page.
+        const rowCursorContext = buildPageContextKey([
+            version,
+            className,
+            classNameMapping,
+            (input.includeKinds ?? []).join(","),
+            input.sourcePriority,
+            resolveGradleUserHomePath(input.gradleUserHome)
+        ]);
+        const { offset: rowOffset, cursorIgnored: rowCursorIgnored } = resolveCursorOffset(input.cursor, rowCursorContext);
+        const windowBase = rowLimit != null ? dedupedBase.slice(rowOffset, rowOffset + rowLimit) : dedupedBase.slice(rowOffset);
+        const consumedRows = rowOffset + windowBase.length;
+        const rowsTruncated = consumedRows < rowCount;
+        const nextCursor = rowsTruncated ? encodeOffsetCursor(consumedRows, rowCursorContext) : undefined;
+        // Map ONLY the requested window. Per-row mapping cost is therefore O(window),
+        // not O(rowCount). warnings/ambiguousRowCount are accordingly page-scoped on
+        // paginated calls (caveat B1) and byte-identical to the old full-set values when
+        // no maxRows/cursor narrows the window.
+        const rows = [];
+        let ambiguousRowCount = 0;
+        for (const baseRecord of windowBase) {
             let rowHadAmbiguity = false;
             const row = {
                 kind: baseRecord.kind,
@@ -584,9 +634,6 @@ export class MappingService {
                 ambiguousRowCount += 1;
             }
         }
-        const rowCount = rows.length;
-        const rowLimit = clampRowLimit(input.maxRows);
-        const limitedRows = rowLimit != null && rowCount > rowLimit ? rows.slice(0, rowLimit) : rows;
         return {
             version,
             className,
@@ -597,9 +644,11 @@ export class MappingService {
                 intermediary: classByMapping.intermediary?.symbol,
                 yarn: classByMapping.yarn?.symbol
             },
-            rows: limitedRows,
+            rows,
             rowCount,
-            rowsTruncated: limitedRows.length < rowCount ? true : undefined,
+            rowsTruncated: rowsTruncated ? true : undefined,
+            ...(nextCursor ? { nextCursor } : {}),
+            ...(rowCursorIgnored ? { cursorIgnored: true } : {}),
             warnings,
             ambiguousRowCount: ambiguousRowCount > 0 ? ambiguousRowCount : undefined
         };
@@ -632,6 +681,11 @@ export class MappingService {
             sourcePriorityApplied: priority
         };
         const classNameMode = input.nameMode === "auto" ? "auto" : "fqcn";
+        // Normalize the effective signatureMode exactly once (mirrors findMapping) so an omitted
+        // signatureMode reaching the service — direct/internal callers, MCP resource handlers, and
+        // batch-symbol-exists entries — defaults to name-only instead of taking the strict
+        // descriptor-required path. Callers needing strict matching pass signatureMode: "exact".
+        const effectiveSignatureMode = input.signatureMode ?? "name-only";
         const normalizedQuery = input.kind === "class" && classNameMode === "auto"
             ? (() => {
                 const owner = input.owner?.trim();
@@ -663,7 +717,9 @@ export class MappingService {
                 };
             })()
             : (() => {
-                const { record: queryRecord, querySymbol } = normalizeQuerySymbol(input, input.signatureMode);
+                const { record: queryRecord, querySymbol } = normalizeQuerySymbol(input, effectiveSignatureMode, {
+                    allowShortClassName: input.kind === "class" && sourceMapping === "obfuscated"
+                });
                 return {
                     mode: "strict",
                     queryRecord,
@@ -684,6 +740,7 @@ export class MappingService {
                 warnings
             };
         }
+        const exactIndex = collectExactRecordIndex(graph, sourceMapping);
         const buildOutput = (querySymbol, matched, status) => {
             const candidates = matched.map((record) => toResolutionCandidate(toLookupCandidate(record)));
             const limitedCandidates = limitResolutionCandidates(candidates, input.maxCandidates);
@@ -705,11 +762,11 @@ export class MappingService {
         if (normalizedQuery.mode === "auto-class") {
             const autoClassName = normalizedQuery.className;
             if (autoClassName.includes(".")) {
-                const matched = records.filter((record) => record.kind === "class" && record.symbol === autoClassName);
+                const matched = lookupExactClassBySymbol(exactIndex, autoClassName);
                 const status = matched.length === 1 ? "resolved" : matched.length > 1 ? "ambiguous" : "not_found";
                 return buildOutput(normalizedQuery.querySymbol, matched, status);
             }
-            const matched = records.filter((record) => record.kind === "class" && record.name === autoClassName);
+            const matched = lookupExactClassBySimpleName(exactIndex, autoClassName);
             const status = matched.length === 1 ? "resolved" : matched.length > 1 ? "ambiguous" : "not_found";
             if (status === "ambiguous") {
                 warnings.push(`Multiple class symbols matched short name "${autoClassName}". Provide fully-qualified class name.`);
@@ -718,18 +775,18 @@ export class MappingService {
         }
         const { queryRecord, querySymbol } = normalizedQuery;
         if (queryRecord.kind === "class") {
-            const matched = records.filter((record) => record.kind === "class" && record.symbol === queryRecord.symbol);
+            const matched = lookupExactClassBySymbol(exactIndex, queryRecord.symbol);
             const status = matched.length === 1 ? "resolved" : matched.length > 1 ? "ambiguous" : "not_found";
             return buildOutput(querySymbol, matched, status);
         }
         if (queryRecord.kind === "field") {
-            const matched = records.filter((record) => record.kind === "field" && record.owner === queryRecord.owner && record.name === queryRecord.name);
+            const matched = lookupExactMembers(exactIndex, "field", queryRecord.owner ?? "", queryRecord.name);
             const status = matched.length === 1 ? "resolved" : matched.length > 1 ? "ambiguous" : "not_found";
             return buildOutput(querySymbol, matched, status);
         }
-        const methodCandidates = records.filter((record) => record.kind === "method" && record.owner === queryRecord.owner && record.name === queryRecord.name);
+        const methodCandidates = lookupExactMembers(exactIndex, "method", queryRecord.owner ?? "", queryRecord.name);
         // name-only mode: skip descriptor matching, resolve by owner+name
-        if (input.signatureMode === "name-only") {
+        if (effectiveSignatureMode === "name-only") {
             const status = methodCandidates.length === 1 ? "resolved" : methodCandidates.length > 1 ? "ambiguous" : "not_found";
             if (status === "ambiguous") {
                 // name-only discards any supplied descriptor, so telling the caller to "provide
@@ -754,18 +811,27 @@ export class MappingService {
         // 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.
+        // Stored descriptors carry whatever coordinate the tiny column used: obfuscated
+        // for merged graphs, but intermediary for a standalone Fabric yarn tiny
+        // (`tiny 2 0 intermediary named`). The descriptor namespace is not recorded
+        // per record, so project the query descriptor along every reachable base
+        // namespace and accept a match in any of them rather than assuming obfuscated.
         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 candidateDescriptors = new Set([queryDescriptor]);
+        for (const baseNamespace of ["obfuscated", "intermediary"]) {
+            if (sourceMapping === baseNamespace) {
+                continue;
+            }
+            const projectionPath = namespacePath(graph, sourceMapping, baseNamespace);
+            if (!projectionPath) {
+                continue;
+            }
+            const projection = this.projectMethodDescriptorToTarget(graph, projectionPath, queryDescriptor);
+            if (projection.hadClassReferences) {
+                candidateDescriptors.add(projection.descriptor);
             }
         }
-        const descriptorMatched = methodCandidates.filter((record) => record.descriptor === effectiveDescriptor || record.descriptor === queryDescriptor);
+        const descriptorMatched = methodCandidates.filter((record) => record.descriptor != null && candidateDescriptors.has(record.descriptor));
         if (descriptorMatched.length === 1) {
             return buildOutput(querySymbol, descriptorMatched, "resolved");
         }
@@ -782,6 +848,9 @@ export class MappingService {
         if (sourceMapping === targetMapping) {
             return [record];
         }
+        // Count genuine cross-namespace path walks (the per-row cost getClassApiMatrix
+        // now scopes to the requested window); test seam via apiMatrixStats.
+        this.apiMatrixRowMaps += 1;
         const path = resolvedPath ?? namespacePath(graph, sourceMapping, targetMapping);
         if (!path) {
             return [];
@@ -886,22 +955,35 @@ export class MappingService {
     projectMethodDescriptorToTarget(graph, path, descriptor) {
         let hadClassReferences = false;
         let complete = true;
-        const classProjectionCache = new Map();
+        // Class-to-class projection depends only on (graph, path, internalName) — not on
+        // the descriptor — so memoize it on the graph and share it across every member
+        // lookup on this graph instead of rebuilding a fresh cache per call. A `null`
+        // entry memoizes an unmapped/ambiguous class so a repeat reference stays
+        // `complete=false` without recomputing.
+        const projectionKey = path.join(">");
+        const classProjectionCache = graph.classProjectionCache;
         const projectedDescriptor = descriptor.replace(/L([^;]+);/g, (fullMatch, internalName) => {
             hadClassReferences = true;
-            const cached = classProjectionCache.get(internalName);
-            if (cached) {
+            const cacheKey = `${projectionKey}\0${internalName}`;
+            const cached = classProjectionCache.get(cacheKey);
+            if (cached !== undefined) {
+                if (cached === null) {
+                    complete = false;
+                    return fullMatch;
+                }
                 return `L${cached};`;
             }
+            this.classProjectionComputes += 1;
             const projectedClassCandidates = this
                 .mapCandidatesAlongPath(graph, path, createClassSymbolRecord(internalName.replace(/\//g, ".")))
                 .filter((candidate) => candidate.kind === "class");
             if (projectedClassCandidates.length !== 1) {
                 complete = false;
+                classProjectionCache.set(cacheKey, null);
                 return fullMatch;
             }
             const projectedInternalName = projectedClassCandidates[0].symbol.replace(/\./g, "/");
-            classProjectionCache.set(internalName, projectedInternalName);
+            classProjectionCache.set(cacheKey, projectedInternalName);
             return `L${projectedInternalName};`;
         });
         return {
@@ -1031,6 +1113,8 @@ export class MappingService {
                 adjacency: new Map(),
                 pathCache: new Map(),
                 recordsByTarget: new Map(),
+                exactRecordIndex: new Map(),
+                classProjectionCache: new Map(),
                 warnings: [
                     `Version ${version} is unobfuscated; mapping graph is empty because the runtime already uses deobfuscated names.`
                 ]
@@ -1044,6 +1128,8 @@ export class MappingService {
             adjacency: new Map(),
             pathCache: new Map(),
             recordsByTarget: new Map(),
+            exactRecordIndex: new Map(),
+            classProjectionCache: new Map(),
             warnings: []
         };
         const mojangLoad = await this.loadMojangPairs(version);
@@ -1209,25 +1295,68 @@ async function extractTinyFromJar(jarPath, outputPath) {
         return false;
     }
     await mkdir(dirname(outputPath), { recursive: true });
-    await writeFile(outputPath, tinyEntry.content, "utf8");
+    const tempPath = `${outputPath}.${randomBytes(4).toString("hex")}.tmp`;
+    await writeFile(tempPath, tinyEntry.content, "utf8");
+    await rename(tempPath, outputPath);
     return true;
 }
+/**
+ * How long a resolved yarn build coordinate is trusted before re-checking the
+ * Fabric Maven metadata for a newer build. Within this window, resolving a yarn
+ * tiny is zero-network (it reuses the recorded coordinate); after it expires the
+ * next resolve does ONE metadata fetch. This fence keeps the metadata fetch off
+ * the remap cache-hit fast path while still picking up new yarn builds.
+ */
+const YARN_METADATA_TTL_MS = 24 * 60 * 60 * 1000;
+function yarnMetaPath(cacheDir, version) {
+    return join(cacheDir, "mappings", "yarn", `${version}.meta.json`);
+}
+function yarnCoordinateTinyPath(cacheDir, coordinate) {
+    return join(cacheDir, "mappings", "yarn", `${coordinate}.tiny`);
+}
+function readYarnCoordinateMeta(metaPath) {
+    if (!existsSync(metaPath)) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(metaPath, "utf8"));
+        if (typeof parsed.coordinate === "string" && typeof parsed.fetchedAt === "number") {
+            return { coordinate: parsed.coordinate, fetchedAt: parsed.fetchedAt };
+        }
+    }
+    catch {
+        // Corrupt marker -> treat as absent and re-resolve.
+    }
+    return undefined;
+}
+function writeYarnCoordinateMeta(metaPath, meta) {
+    mkdirSync(dirname(metaPath), { recursive: true });
+    writeFileSync(metaPath, JSON.stringify(meta));
+}
 /**
  * Resolve and cache a Tiny v2 mapping file for the given Minecraft version.
  *
+ * Intermediary is version-keyed (immutable per release). Yarn is coordinate-keyed:
+ * Fabric publishes incrementing yarn builds for the same MC version, so the tiny
+ * is cached at `mappings/yarn/${coordinate}.tiny` and the newest coordinate is
+ * re-checked once per {@link YARN_METADATA_TTL_MS}. The resolved yarn coordinate
+ * is returned so callers can key their own caches on the actual mappings used.
+ *
  * @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
+ * @param options - forceRefresh bypasses the yarn metadata TTL; now overrides the clock (testing)
+ * @returns The extracted Tiny v2 path and, for yarn, the resolved build coordinate
  */
-export async function resolveTinyMappingFile(version, mapping, cacheDir, fetchFn) {
-    const cachedTiny = join(cacheDir, "mappings", `${version}-${mapping}.tiny`);
-    if (existsSync(cachedTiny)) {
-        return cachedTiny;
-    }
+export async function resolveTinyMappingFile(version, mapping, cacheDir, fetchFn, options) {
     const effectiveFetch = fetchFn ?? globalThis.fetch;
     if (mapping === "intermediary") {
+        // Intermediary is immutable per MC release: version-keyed cache is correct.
+        const cachedTiny = join(cacheDir, "mappings", `${version}-intermediary.tiny`);
+        if (existsSync(cachedTiny)) {
+            return { path: cachedTiny };
+        }
         const url = `${FABRIC_MAVEN}/net/fabricmc/intermediary/${version}/intermediary-${version}-v2.jar`;
         const jarDest = defaultDownloadPath(cacheDir, url);
         const downloaded = await downloadToCache(url, jarDest, {
@@ -1250,11 +1379,30 @@ export async function resolveTinyMappingFile(version, mapping, cacheDir, fetchFn
                 details: { version, jarPath: downloaded.path }
             });
         }
-        return cachedTiny;
+        return { path: cachedTiny };
+    }
+    // yarn: coordinate-keyed + metadata-TTL fenced.
+    const nowFn = options?.now ?? Date.now;
+    const metaPath = yarnMetaPath(cacheDir, version);
+    const existingMeta = readYarnCoordinateMeta(metaPath);
+    // Within-TTL fast path: reuse the recorded coordinate with zero network.
+    if (!options?.forceRefresh && existingMeta && nowFn() - existingMeta.fetchedAt < YARN_METADATA_TTL_MS) {
+        const cachedCoordTiny = yarnCoordinateTinyPath(cacheDir, existingMeta.coordinate);
+        if (existsSync(cachedCoordTiny)) {
+            return { path: cachedCoordTiny, coordinate: existingMeta.coordinate };
+        }
     }
-    // yarn
     const yarnCoordinates = await fetchYarnCoordinatesStandalone(version, effectiveFetch);
+    // Network fallback: the metadata fetch failed/empty (fetchYarnCoordinatesStandalone
+    // swallows errors -> []). Serve the last-known-good coordinate rather than failing,
+    // so a transient Fabric Maven outage after TTL expiry does not break cache hits.
     if (yarnCoordinates.length === 0) {
+        if (existingMeta) {
+            const cachedCoordTiny = yarnCoordinateTinyPath(cacheDir, existingMeta.coordinate);
+            if (existsSync(cachedCoordTiny)) {
+                return { path: cachedCoordTiny, coordinate: existingMeta.coordinate };
+            }
+        }
         throw createError({
             code: ERROR_CODES.MAPPING_UNAVAILABLE,
             message: `No yarn builds found for Minecraft ${version}.`,
@@ -1262,6 +1410,12 @@ export async function resolveTinyMappingFile(version, mapping, cacheDir, fetchFn
         });
     }
     for (const coordinate of yarnCoordinates) {
+        const coordTiny = yarnCoordinateTinyPath(cacheDir, coordinate);
+        if (existsSync(coordTiny)) {
+            // Already have this build's tiny; just refresh the TTL marker.
+            writeYarnCoordinateMeta(metaPath, { coordinate, fetchedAt: nowFn() });
+            return { path: coordTiny, coordinate };
+        }
         const url = `${FABRIC_MAVEN}/net/fabricmc/yarn/${coordinate}/yarn-${coordinate}-v2.jar`;
         const jarDest = defaultDownloadPath(cacheDir, url);
         const downloaded = await downloadToCache(url, jarDest, {
@@ -1272,9 +1426,12 @@ export async function resolveTinyMappingFile(version, mapping, cacheDir, fetchFn
         if (!downloaded.ok || !downloaded.path) {
             continue;
         }
-        const extracted = await extractTinyFromJar(downloaded.path, cachedTiny);
+        const extracted = await extractTinyFromJar(downloaded.path, coordTiny);
         if (extracted) {
-            return cachedTiny;
+            // Ordering matters: the tiny exists before the marker is written, so a
+            // crash never leaves a TTL-valid marker pointing at a missing tiny.
+            writeYarnCoordinateMeta(metaPath, { coordinate, fetchedAt: nowFn() });
+            return { path: coordTiny, coordinate };
         }
     }
     throw createError({

package/dist/mcp-helpers.d.ts

@@ -9,5 +9,6 @@ export declare function objectResource(uri: string, data: Record<string, unknown
 export declare function errorResource(uri: string, error: string | {
     message: string;
     code?: ErrorCode;
+    details?: unknown;
 }): ReadResourceResult;
 export {};

package/dist/mcp-helpers.js

@@ -1,4 +1,6 @@
 import { ERROR_CODES } from "./errors.js";
+import { retryClassForErrorCode, issueOriginForErrorCode, extractAllowlistedContext } from "./error-mapping.js";
+import { toHints, extractValidatedSuggestionAndExamples, extractFieldErrorsFromDetails } from "./tool-guidance.js";
 export function objectResult(data, options = {}) {
     return {
         content: [{ type: "text", text: JSON.stringify(data) }],
@@ -42,8 +44,18 @@ function statusForResourceErrorCode(code) {
     return 500;
 }
 export function errorResource(uri, error) {
-    const detail = typeof error === "string" ? error : error.message;
-    const code = typeof error === "string" ? ERROR_CODES.INVALID_INPUT : error.code ?? ERROR_CODES.INTERNAL;
+    const isStr = typeof error === "string";
+    const detail = isStr ? error : error.message;
+    const code = isStr ? ERROR_CODES.INVALID_INPUT : error.code ?? ERROR_CODES.INTERNAL;
+    // Resource reads carry the same AppError as the equivalent tool call, so they
+    // get the same recovery metadata. Classifiers are always present; the rest is
+    // extracted from the AppError details (reusing the tool-error helpers as-is so
+    // the suggestedCall is validated through the single buildSuggestedCall gate).
+    const details = isStr ? undefined : error.details;
+    const hints = toHints(details);
+    const { suggestedCall, exampleCalls } = extractValidatedSuggestionAndExamples(details);
+    const fieldErrors = extractFieldErrorsFromDetails(details);
+    const context = extractAllowlistedContext(details);
     return {
         contents: [
             {
@@ -51,12 +63,22 @@ export function errorResource(uri, error) {
                 mimeType: "application/json",
                 text: JSON.stringify({
                     error: {
+                        // Keep the generic resource type/title (asserted by tests and
+                        // intentionally distinct from the per-code tool ProblemDetails) so
+                        // the two access paths stay distinguishable.
                         type: "https://minecraft-modding-mcp.dev/problems/resource",
                         title: "Resource read failed",
                         detail,
                         status: statusForResourceErrorCode(code),
                         code,
-                        instance: uri
+                        instance: uri,
+                        retryClass: retryClassForErrorCode(code),
+                        issueOrigin: issueOriginForErrorCode(code),
+                        ...(fieldErrors ? { fieldErrors } : {}),
+                        ...(hints ? { hints } : {}),
+                        ...(suggestedCall ? { suggestedCall } : {}),
+                        ...(exampleCalls ? { exampleCalls } : {}),
+                        ...(context ? { context } : {})
                     },
                     meta: { uri }
                 })

package/dist/minecraft-explorer-service.js

@@ -1,7 +1,7 @@
 import { createError, ERROR_CODES } from "./errors.js";
 import { loadConfig } from "./config.js";
 import { artifactSignatureFromFile, normalizeJarPath } from "./path-resolver.js";
-import { readJarEntryAsBuffer } from "./source-jar-reader.js";
+import { createJarEntryReader } from "./source-jar-reader.js";
 const CLASSFILE_MAGIC = 0xcafebabe;
 const MAX_INHERITANCE_DEPTH = 64;
 const ACC_PUBLIC = 0x0001;
@@ -452,18 +452,28 @@ export class MinecraftExplorerService {
             };
         }
         const classEntryPath = `${toInternalName(fqn)}.class`;
-        let classBuffer;
+        // Open the jar ONCE for this call; every hierarchy class is served from the
+        // same handle (see reader.close() after hierarchy construction below).
+        const reader = await createJarEntryReader(jarPath);
+        let parsed;
         try {
-            classBuffer = await readJarEntryAsBuffer(jarPath, classEntryPath);
+            let classBuffer;
+            try {
+                classBuffer = await reader.getEntryBuffer(classEntryPath);
+            }
+            catch {
+                throw createError({
+                    code: ERROR_CODES.CLASS_NOT_FOUND,
+                    message: `Class "${fqn}" was not found in "${jarPath}".`,
+                    details: { fqn, jarPath, classEntryPath }
+                });
+            }
+            parsed = parseClassFile(classBuffer);
         }
-        catch {
-            throw createError({
-                code: ERROR_CODES.CLASS_NOT_FOUND,
-                message: `Class "${fqn}" was not found in "${jarPath}".`,
-                details: { fqn, jarPath, classEntryPath }
-            });
+        catch (error) {
+            reader.close();
+            throw error;
         }
-        const parsed = parseClassFile(classBuffer);
         const parsedClassCache = new Map([[parsed.internalName, parsed]]);
         const warnings = [];
         const warnMissingInheritedClass = (internalName, relation) => {
@@ -476,7 +486,7 @@ export class MinecraftExplorerService {
             }
             const classPath = `${internalName}.class`;
             try {
-                const classBytes = await readJarEntryAsBuffer(jarPath, classPath);
+                const classBytes = await reader.getEntryBuffer(classPath);
                 const parsedClass = parseClassFile(classBytes);
                 parsedClassCache.set(parsedClass.internalName, parsedClass);
                 return parsedClass;
@@ -540,6 +550,9 @@ export class MinecraftExplorerService {
             }
             hierarchyClasses.push(...interfaceClasses);
         }
+        // All jar reads are done; release the file descriptor before member projection
+        // (which performs no IO but may throw on malformed descriptors).
+        reader.close();
         const toSignatureMember = (ownerFqn, ownerSimpleClassName, member, category) => {
             if (category === "field") {
                 const parsedField = parseFieldType(member.descriptor, 0, { allowVoid: false });