@adhisang/minecraft-modding-mcp 4.2.0 → 5.0.0

package/dist/mapping/types.d.ts

@@ -55,6 +55,7 @@ export type FindMappingInput = {
     name: string;
     owner?: string;
     descriptor?: string;
+    nameMode?: "fqcn" | "auto";
     signatureMode?: "exact" | "name-only";
     sourceMapping: SourceMapping;
     targetMapping: SourceMapping;
@@ -103,6 +104,7 @@ export type ClassApiMatrixInput = {
     gradleUserHome?: string;
     includeKinds?: ClassApiMatrixKind[];
     maxRows?: number;
+    cursor?: string;
 };
 export type ClassApiMatrixEntry = {
     symbol: string;
@@ -127,6 +129,10 @@ export type ClassApiMatrixOutput = {
     rows: ClassApiMatrixRow[];
     rowCount: number;
     rowsTruncated?: boolean;
+    /** Continuation cursor when more rows remain; pass back as cursor for the next page. */
+    nextCursor?: string;
+    /** True when a provided cursor was malformed or belonged to a different query and was ignored. */
+    cursorIgnored?: boolean;
     warnings: string[];
     ambiguousRowCount?: number;
 };

package/dist/mapping-service.d.ts

@@ -14,11 +14,21 @@ export declare class MappingService {
     private static readonly RESOLUTION_CACHE_TTL_MS;
     private resolutionCacheHits;
     private resolutionCacheMisses;
+    private classProjectionComputes;
+    private apiMatrixRowMaps;
     get resolutionCacheStats(): {
         hits: number;
         misses: number;
         size: number;
     };
+    /** Test seam: counts genuine class-projection computes (cache misses). */
+    get classProjectionStats(): {
+        computes: number;
+    };
+    /** Test seam: counts genuine per-row cross-namespace path walks in getClassApiMatrix. */
+    get apiMatrixStats(): {
+        rowMaps: number;
+    };
     constructor(config: Config, versionService?: VersionMappingsResolver, fetchFn?: typeof fetch);
     findMapping(input: FindMappingInput): Promise<FindMappingOutput>;
     ensureMappingAvailable(input: EnsureMappingAvailableInput): Promise<EnsureMappingAvailableOutput>;
@@ -60,13 +70,27 @@ export declare class MappingService {
     private buildResolutionCacheKey;
     private trimResolutionCache;
 }
+export type ResolvedTinyMapping = {
+    path: string;
+    coordinate?: string;
+};
 /**
  * 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 declare function resolveTinyMappingFile(version: string, mapping: "intermediary" | "yarn", cacheDir: string, fetchFn?: typeof fetch): Promise<string>;
+export declare function resolveTinyMappingFile(version: string, mapping: "intermediary" | "yarn", cacheDir: string, fetchFn?: typeof fetch, options?: {
+    forceRefresh?: boolean;
+    now?: () => number;
+}): Promise<ResolvedTinyMapping>;

package/dist/mapping-service.js

@@ -1,8 +1,9 @@
-import { existsSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 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";
@@ -32,6 +33,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 +42,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 +76,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 +187,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}.`);
         }
@@ -511,9 +522,6 @@ export class MappingService {
             }
             return includeKinds.has("method");
         });
-        const rows = [];
-        let ambiguousRowCount = 0;
-        const rowSeen = new Set();
         const rowKindOrder = {
             class: 0,
             field: 1,
@@ -530,12 +538,46 @@ 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
+        ]);
+        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 +626,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 +636,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 +673,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 +709,7 @@ export class MappingService {
                 };
             })()
             : (() => {
-                const { record: queryRecord, querySymbol } = normalizeQuerySymbol(input, input.signatureMode);
+                const { record: queryRecord, querySymbol } = normalizeQuerySymbol(input, effectiveSignatureMode);
                 return {
                     mode: "strict",
                     queryRecord,
@@ -729,7 +775,7 @@ export class MappingService {
         }
         const methodCandidates = records.filter((record) => record.kind === "method" && record.owner === queryRecord.owner && record.name === 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 +800,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 +837,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 +944,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 +1102,7 @@ export class MappingService {
                 adjacency: new Map(),
                 pathCache: new Map(),
                 recordsByTarget: new Map(),
+                classProjectionCache: new Map(),
                 warnings: [
                     `Version ${version} is unobfuscated; mapping graph is empty because the runtime already uses deobfuscated names.`
                 ]
@@ -1044,6 +1116,7 @@ export class MappingService {
             adjacency: new Map(),
             pathCache: new Map(),
             recordsByTarget: new Map(),
+            classProjectionCache: new Map(),
             warnings: []
         };
         const mojangLoad = await this.loadMojangPairs(version);
@@ -1212,22 +1285,63 @@ async function extractTinyFromJar(jarPath, outputPath) {
     await writeFile(outputPath, tinyEntry.content, "utf8");
     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 +1364,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 +1395,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 +1411,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 });

package/dist/mixin/access-validators.js

@@ -183,6 +183,17 @@ export function validateParsedAccessTransformer(parsed, membersByClass, warnings
             invalidCount++;
             continue;
         }
+        if (entry.targetKind === "wildcard-all" || entry.targetKind === "wildcard-method") {
+            // A wildcard transforms all members (or all methods); it is valid as long as
+            // the owner class resolved, which it has by this point.
+            validatedEntries.push({
+                ...entry,
+                valid: true,
+                ...(options?.includeRuntimeEvidence ? { resolvedInRuntime: true } : {})
+            });
+            validCount++;
+            continue;
+        }
         if (entry.targetKind === "field") {
             const fieldNames = allFieldNames(members);
             const matchedField = members.fields.find((member) => member.name === entry.name);
@@ -215,8 +226,29 @@ export function validateParsedAccessTransformer(parsed, membersByClass, warnings
             continue;
         }
         const methodNames = allMethodNames(members);
-        const matchedMethod = members.methods.find((member) => member.name === entry.name && member.jvmDescriptor === entry.descriptor) ?? members.constructors.find((member) => member.name === entry.name && member.jvmDescriptor === entry.descriptor);
+        const sameNameMethods = [...members.methods, ...members.constructors].filter((member) => member.name === entry.name);
+        // Match by descriptor when one is supplied (AT method lines always carry one);
+        // fall back to a unique name match when it is absent.
+        const matchedMethod = entry.descriptor
+            ? sameNameMethods.find((member) => member.jvmDescriptor === entry.descriptor)
+            : sameNameMethods.length === 1
+                ? sameNameMethods[0]
+                : undefined;
         if (!matchedMethod) {
+            // Distinguish a true missing method from a descriptor mismatch so the user
+            // can see which overloads exist instead of a flat "not found".
+            if (entry.descriptor && sameNameMethods.length > 0) {
+                const available = [...new Set(sameNameMethods.map((member) => member.jvmDescriptor))];
+                validatedEntries.push({
+                    ...entry,
+                    valid: false,
+                    issue: `Method "${entry.name}" exists in "${ownerFqn}" but no overload matches descriptor ${entry.descriptor} (available: ${available.join(", ")}).`,
+                    suggestions: available,
+                    ...(options?.includeRuntimeEvidence ? { resolvedInRuntime: false } : {})
+                });
+                invalidCount++;
+                continue;
+            }
             const suggestions = entry.name ? suggestSimilar(entry.name, methodNames) : [];
             validatedEntries.push({
                 ...entry,