@adhisang/minecraft-modding-mcp 5.0.0 → 6.0.0

package/dist/index.js

@@ -15,7 +15,7 @@ import { remapModJar } from "./mod-remap-service.js";
 import { registerResources } from "./resources.js";
 import { SourceService } from "./source-service.js";
 import { ToolExecutionGate } from "./tool-execution-gate.js";
-import { classifyWarnings } from "./warning-details.js";
+import { capWarningDetailsForSummary, classifyWarnings } from "./warning-details.js";
 import { WorkspaceMappingService } from "./workspace-mapping-service.js";
 import { InspectMinecraftService, inspectMinecraftSchema, inspectMinecraftShape } from "./entry-tools/inspect-minecraft-service.js";
 import { AnalyzeSymbolService, analyzeSymbolSchema, analyzeSymbolShape } from "./entry-tools/analyze-symbol-service.js";
@@ -90,7 +90,7 @@ server.validateToolInput = async (_tool, args) => args;
 // server.tool() but appends a note steering agents to the entry tools first.
 // Entry tools, batch tools, and the NBT/runtime utilities (which have no entry
 // equivalent) keep their plain descriptions via server.tool().
-const EXPERT_TOOL_NOTE = " Expert/follow-up tool: prefer the entry tools (inspect-minecraft, analyze-symbol, compare-minecraft, analyze-mod, validate-project) first; reach for this only for the narrow operation it names.";
+const EXPERT_TOOL_NOTE = " Expert tool: prefer the entry tools (inspect-minecraft, analyze-symbol, compare-minecraft, analyze-mod, validate-project) first.";
 const expertTool = ((name, description, ...rest) => server.tool(name, description + EXPERT_TOOL_NOTE, ...rest));
 const config = loadConfig();
 const nbtLimits = {
@@ -385,18 +385,23 @@ async function runTool(tool, rawInput, schema, action) {
         if (DETAIL_ENABLED_TOOL_NAMES.has(tool)) {
             projectedResult = projectByDetail(tool, projectedResult, effectiveDetail, shapeInput.include);
         }
-        // Entry, expert, and batch tools all report the applied detail/include shape in meta.
+        // Entry, expert, and batch tools report the applied detail/include shape in meta.
+        // detailApplied is omitted when it matches the tool's default to keep responses lean.
+        const defaultDetail = ENTRY_TOOL_NAMES.has(tool)
+            ? "summary"
+            : DEFAULT_DETAIL_BY_TOOL[tool] ?? "summary";
         const entryMeta = ENTRY_TOOL_NAMES.has(tool) ||
             DETAIL_ENABLED_TOOL_NAMES.has(tool) ||
             BATCH_DETAIL_TOOL_NAMES.has(tool)
             ? buildEntryToolMeta({
                 detail: effectiveDetail,
+                defaultDetail,
                 include: shapeInput.include.size > 0 ? [...shapeInput.include] : undefined
             })
             : undefined;
         const durationMs = Date.now() - startedAt;
         sourceService.recordToolCall(tool, durationMs);
-        const warningDetails = classifyWarnings(warnings);
+        const warningDetails = capWarningDetailsForSummary(classifyWarnings(warnings), effectiveDetail === "summary");
         return objectResult({
             result: projectedResult,
             meta: {
@@ -405,7 +410,7 @@ async function runTool(tool, rawInput, schema, action) {
                 requestId,
                 tool,
                 durationMs,
-                warnings,
+                ...(warnings.length > 0 ? { warnings } : {}),
                 ...(warningDetails.length > 0 ? { warningDetails } : {})
             }
         });
@@ -450,8 +455,7 @@ async function runTool(tool, rawInput, schema, action) {
         const errorMeta = {
             requestId,
             tool,
-            durationMs: errorDurationMs,
-            warnings: []
+            durationMs: errorDurationMs
         };
         applyErrorMetaExtensions(errorMeta, caughtError);
         return objectResult({
@@ -467,7 +471,7 @@ expertTool("list-versions", "List available Minecraft versions from Mojang manif
 registerToolSchema("list-versions", listVersionsSchema);
 server.tool("inspect-minecraft", "Top-level workflow tool for version discovery, artifact resolution, class inspection, source search, file reads, and file listings.", inspectMinecraftShape, { readOnlyHint: true }, async (args) => runTool("inspect-minecraft", args, inspectMinecraftSchema, async (input) => inspectMinecraftService.execute(input)));
 registerToolSchema("inspect-minecraft", inspectMinecraftSchema);
-server.tool("analyze-symbol", "Top-level workflow tool for symbol existence, mapping, lifecycle (with fromVersion/toVersion/maxVersions/includeTimeline range controls), workspace analysis, and API overview. subject.kind accepts 'symbol' to auto-detect class/field/method from the selector (inferred kind is returned as a warning).", analyzeSymbolShape, { readOnlyHint: true }, async (args) => runTool("analyze-symbol", args, analyzeSymbolSchema, async (input) => analyzeSymbolService.execute(input)));
+server.tool("analyze-symbol", "Top-level workflow tool for symbol existence, mapping, lifecycle, workspace analysis, and API overview. subject.kind='symbol' auto-detects class/field/method from the selector.", analyzeSymbolShape, { readOnlyHint: true }, async (args) => runTool("analyze-symbol", args, analyzeSymbolSchema, async (input) => analyzeSymbolService.execute(input)));
 registerToolSchema("analyze-symbol", analyzeSymbolSchema);
 server.tool("compare-minecraft", "Top-level workflow tool for version comparisons, class diffs, registry diffs, and migration overviews.", compareMinecraftShape, { readOnlyHint: true }, async (args) => runTool("compare-minecraft", args, compareMinecraftSchema, async (input) => compareMinecraftService.execute(input)));
 registerToolSchema("compare-minecraft", compareMinecraftSchema);
@@ -497,16 +501,16 @@ if (!VERIFY_MIXIN_TARGET_OFF) {
     registerToolSchema("verify-mixin-target", verifyMixinTargetSchema);
 }
 if (!BATCH_TOOLS_OFF) {
-    server.tool("batch-class-source", "Batch lookup: read source for many classes in one call, sharing a single resolved artifact. Returns per-entry { status, result?, error? } plus aggregate summary. Per-entry retry suggestions point at get-class-source. Not read-only: per-entry outputFile writes source files to disk.", batchClassSourceShape, { readOnlyHint: false }, async (args) => runTool("batch-class-source", args, batchClassSourceSchema, async (input) => batchClassSourceService.execute(input)));
+    server.tool("batch-class-source", "Batch get-class-source for many classes sharing one resolved artifact; returns per-entry status plus aggregate summary. Not read-only: per-entry outputFile writes to disk.", batchClassSourceShape, { readOnlyHint: false }, async (args) => runTool("batch-class-source", args, batchClassSourceSchema, async (input) => batchClassSourceService.execute(input)));
     registerToolSchema("batch-class-source", batchClassSourceSchema);
-    server.tool("batch-class-members", "Batch lookup: list members for many classes in one call, sharing a single resolved artifact. Returns per-entry { status, result?, error? } plus aggregate summary. Per-entry retry suggestions point at get-class-members.", batchClassMembersShape, { readOnlyHint: true }, async (args) => runTool("batch-class-members", args, batchClassMembersSchema, async (input) => batchClassMembersService.execute(input)));
+    server.tool("batch-class-members", "Batch get-class-members for many classes sharing one resolved artifact; returns per-entry status plus aggregate summary.", batchClassMembersShape, { readOnlyHint: true }, async (args) => runTool("batch-class-members", args, batchClassMembersSchema, async (input) => batchClassMembersService.execute(input)));
     registerToolSchema("batch-class-members", batchClassMembersSchema);
-    server.tool("batch-symbol-exists", "Batch existence/mapping query: probe many symbols in one call against a shared Minecraft-version artifact. Accepts target.kind=workspace or version only (other kinds carry library versions, not Minecraft versions). Per-entry retry suggestions point at check-symbol-exists.", batchSymbolExistsShape, { readOnlyHint: true }, async (args) => runTool("batch-symbol-exists", args, batchSymbolExistsSchema, async (input) => batchSymbolExistsService.execute(input)));
+    server.tool("batch-symbol-exists", "Batch check-symbol-exists for many symbols against one shared Minecraft version (target.kind=version or workspace only).", batchSymbolExistsShape, { readOnlyHint: true }, async (args) => runTool("batch-symbol-exists", args, batchSymbolExistsSchema, async (input) => batchSymbolExistsService.execute(input)));
     registerToolSchema("batch-symbol-exists", batchSymbolExistsSchema);
-    server.tool("batch-mappings", "Batch mapping translation: resolve many symbols across mapping namespaces with one shared Minecraft version. Per-entry retry suggestions point at find-mapping.", batchMappingsShape, { readOnlyHint: true }, async (args) => runTool("batch-mappings", args, batchMappingsSchema, async (input) => batchMappingsService.execute(input)));
+    server.tool("batch-mappings", "Batch find-mapping: resolve many symbols across mapping namespaces with one shared Minecraft version.", batchMappingsShape, { readOnlyHint: true }, async (args) => runTool("batch-mappings", args, batchMappingsSchema, async (input) => batchMappingsService.execute(input)));
     registerToolSchema("batch-mappings", batchMappingsSchema);
 }
-expertTool("resolve-artifact", "Resolve source artifact from a target object ({ kind, value }) and return artifact metadata. For target.kind=jar, only <basename>-sources.jar is auto-adopted; other adjacent *-sources.jar files are informational.", resolveArtifactShape, { readOnlyHint: true }, async (args) => runTool("resolve-artifact", args, resolveArtifactSchema, async (input) => sourceService.resolveArtifact({
+expertTool("resolve-artifact", "Resolve a source artifact and return artifact metadata. For target.kind=jar, only <basename>-sources.jar is auto-adopted.", resolveArtifactShape, { readOnlyHint: true }, async (args) => runTool("resolve-artifact", args, resolveArtifactSchema, async (input) => sourceService.resolveArtifact({
     target: input.target,
     mapping: input.mapping,
     sourcePriority: input.sourcePriority,
@@ -532,7 +536,7 @@ expertTool("find-class", "Resolve a simple or qualified class name to fully-qual
     limit: input.limit
 })));
 registerToolSchema("find-class", findClassSchema);
-expertTool("get-class-source", "Get Java source for a class by target ({ kind: 'artifact', artifactId } or { kind: 'version'|'jar'|'coordinate'|'workspace'|'dependency', ... } — same shape as resolve-artifact). To read source text, pass mode=snippet (bounded excerpt) or mode=full (entire source); the default mode=metadata returns a symbol outline only, not the body. Not read-only: outputFile writes the source to disk.", getClassSourceShape, { readOnlyHint: false }, async (args) => runTool("get-class-source", args, getClassSourceSchema, async (input) => {
+expertTool("get-class-source", "Get Java source for a class. Default mode=metadata returns a symbol outline only; pass mode=snippet or mode=full to read source text. Not read-only: outputFile writes to disk.", getClassSourceShape, { readOnlyHint: false }, async (args) => runTool("get-class-source", args, getClassSourceSchema, async (input) => {
     const normalizedTarget = normalizeSourceLookupTarget(input.target);
     return sourceService.getClassSource({
         className: input.className,
@@ -555,7 +559,7 @@ expertTool("get-class-source", "Get Java source for a class by target ({ kind: '
     });
 }));
 registerToolSchema("get-class-source", getClassSourceSchema);
-expertTool("get-class-members", "Get fields/methods/constructors for one class from binary bytecode by target ({ kind: 'artifact', artifactId } or { kind: 'version'|'jar'|'coordinate'|'workspace'|'dependency', ... } — same shape as resolve-artifact).", getClassMembersShape, { readOnlyHint: true }, async (args) => runTool("get-class-members", args, getClassMembersSchema, async (input) => {
+expertTool("get-class-members", "Get fields/methods/constructors for one class from binary bytecode.", getClassMembersShape, { readOnlyHint: true }, async (args) => runTool("get-class-members", args, getClassMembersSchema, async (input) => {
     const normalizedTarget = normalizeSourceLookupTarget(input.target);
     return sourceService.getClassMembers({
         className: input.className,
@@ -657,7 +661,7 @@ expertTool("find-mapping", "Find symbol mapping candidates between namespaces us
     maxCandidates: input.maxCandidates
 })));
 registerToolSchema("find-mapping", findMappingSchema);
-expertTool("resolve-method-mapping-exact", "Strict shortcut for find-mapping(kind=method, signatureMode=exact): resolve one method mapping by owner+name+descriptor between namespaces and report resolved/not_found/ambiguous. Stricter than find-mapping's exact mode — it requires a COMPLETE descriptor projection and returns mapping_unavailable when the descriptor's class references cannot all be projected to the target namespace (find-mapping is more lenient there). Use find-mapping kind=method signatureMode=exact unless you specifically need that strict-completeness guarantee.", resolveMethodMappingExactShape, { readOnlyHint: true }, async (args) => runTool("resolve-method-mapping-exact", args, resolveMethodMappingExactSchema, async (input) => sourceService.resolveMethodMappingExact({
+expertTool("resolve-method-mapping-exact", "Strict variant of find-mapping(kind=method, signatureMode=exact): requires a COMPLETE descriptor projection and returns mapping_unavailable when any descriptor class reference cannot be projected. Prefer find-mapping unless you need that guarantee.", resolveMethodMappingExactShape, { readOnlyHint: true }, async (args) => runTool("resolve-method-mapping-exact", args, resolveMethodMappingExactSchema, async (input) => sourceService.resolveMethodMappingExact({
     version: input.version,
     name: input.name,
     owner: input.owner,

package/dist/java-process.js

@@ -107,7 +107,7 @@ export function runJavaProcess(options) {
                 }
             }));
         });
-        proc.once("exit", (code) => {
+        proc.once("close", (code) => {
             clearTimeout(timer);
             resolve({
                 exitCode: code ?? -1,

package/dist/json-rpc-framing.d.ts

@@ -9,6 +9,9 @@ export declare function encodeJsonRpcMessage(message: JSONRPCMessage, mode: Conc
 export declare class JsonRpcFrameReader {
     private mode;
     private buffer;
+    private pendingChunks;
+    private pendingBytes;
+    private awaitedFrameEnd;
     get currentMode(): FramingMode;
     reset(): void;
     clear(): void;
@@ -16,6 +19,7 @@ export declare class JsonRpcFrameReader {
         onFrame: (frame: ParsedJsonRpcFrame) => void;
         onError: (error: Error) => void;
     }): void;
+    private canCompleteFrame;
     private detectMode;
     private readLineDelimitedMessage;
     private readContentLengthMessage;

package/dist/json-rpc-framing.js

@@ -25,21 +25,35 @@ export function encodeJsonRpcMessage(message, mode) {
 export class JsonRpcFrameReader {
     mode = "unknown";
     buffer = Buffer.alloc(0);
+    pendingChunks = [];
+    pendingBytes = 0;
+    awaitedFrameEnd = -1;
     get currentMode() {
         return this.mode;
     }
     reset() {
         this.mode = "unknown";
+        this.awaitedFrameEnd = -1;
     }
     clear() {
         this.mode = "unknown";
         this.buffer = Buffer.alloc(0);
+        this.pendingChunks = [];
+        this.pendingBytes = 0;
+        this.awaitedFrameEnd = -1;
     }
     processChunk(chunk, handlers) {
         if (chunk.length === 0) {
             return;
         }
-        this.buffer = Buffer.concat([this.buffer, chunk]);
+        this.pendingChunks.push(chunk);
+        this.pendingBytes += chunk.length;
+        if (!this.canCompleteFrame(chunk)) {
+            return;
+        }
+        this.buffer = Buffer.concat([this.buffer, ...this.pendingChunks]);
+        this.pendingChunks = [];
+        this.pendingBytes = 0;
         while (true) {
             try {
                 if (this.mode === "unknown") {
@@ -71,6 +85,12 @@ export class JsonRpcFrameReader {
             }
         }
     }
+    canCompleteFrame(chunk) {
+        if (this.mode === "content-length" && this.awaitedFrameEnd >= 0) {
+            return this.buffer.length + this.pendingBytes >= this.awaitedFrameEnd;
+        }
+        return chunk.includes(0x0a);
+    }
     detectMode() {
         while (this.buffer.length > 0) {
             if (this.buffer[0] === 0x0a) {
@@ -124,6 +144,7 @@ export class JsonRpcFrameReader {
         }
     }
     readContentLengthMessage() {
+        this.awaitedFrameEnd = -1;
         const headerBoundary = findHeaderBoundary(this.buffer);
         if (!headerBoundary) {
             return undefined;
@@ -158,6 +179,7 @@ export class JsonRpcFrameReader {
         const messageStart = headerBoundary.index + headerBoundary.delimiterBytes;
         const frameEnd = messageStart + contentLength;
         if (this.buffer.length < frameEnd) {
+            this.awaitedFrameEnd = frameEnd;
             return undefined;
         }
         const body = this.buffer.subarray(messageStart, frameEnd).toString("utf8");

package/dist/mapping/internal-types.d.ts

@@ -20,6 +20,18 @@ export type DirectionIndex = {
     simple: Map<string, Set<string>>;
     records: Map<string, MappingSymbolRecord>;
 };
+/**
+ * O(1) exact-lookup index over a single target namespace's records, used by
+ * existence checks. `byKey` is keyed by `kind|owner|name` (owner empty for
+ * classes, which key on their FQCN symbol); `classBySimpleName` resolves the
+ * auto-class short-name path. Values are arrays so callers can still tell a
+ * unique match (resolved) from multiple (ambiguous).
+ */
+export type ExactRecordIndex = {
+    byKey: Map<string, MappingSymbolRecord[]>;
+    classBySimpleName: Map<string, MappingSymbolRecord[]>;
+    membersByOwner: Map<string, MappingSymbolRecord[]>;
+};
 export type MappingLookupSource = "loom-cache" | "maven" | "mojang-client-mappings";
 export type PairRecord = {
     index: DirectionIndex;
@@ -50,6 +62,11 @@ export type LoadedGraph = {
     adjacency: Map<import("../types.js").SourceMapping, import("../types.js").SourceMapping[]>;
     pathCache: Map<PairKey, import("../types.js").SourceMapping[] | undefined>;
     recordsByTarget: Map<import("../types.js").SourceMapping, MappingSymbolRecord[]>;
+    /**
+     * Graph-scoped, lazily-built exact-lookup indexes keyed by target namespace.
+     * Populated on first existence check for a namespace; dies with graph eviction.
+     */
+    exactRecordIndex: Map<import("../types.js").SourceMapping, ExactRecordIndex>;
     /**
      * Graph-scoped cache of class-to-class descriptor projections, keyed by
      * `path.join(">") + NUL + internalName`. Value is the projected internal name,

package/dist/mapping/loaders/tiny-maven.js

@@ -53,36 +53,62 @@ export async function loadTinyPairsFromMaven(deps, version) {
     const warnings = [];
     const merged = new Map();
     const repos = deps.config.sourceRepos;
-    const intermediaryUrls = [];
-    const yarnUrls = [];
+    const attemptedUrls = [];
     const repoBases = repos.map((repo) => repo.replace(/\/+$/, ""));
     const yarnCoordinatesByRepo = await Promise.all(repoBases.map(async (base) => ({
         base,
         yarnCoordinates: await fetchYarnCoordinates(deps.fetchFn, base, version)
     })));
+    const tryUrls = async (urls) => {
+        for (const url of urls) {
+            attemptedUrls.push(url);
+            try {
+                const downloaded = await downloadToCache(url, defaultDownloadPath(deps.config.cacheDir, url), {
+                    fetchFn: deps.fetchFn,
+                    retries: deps.config.fetchRetries,
+                    timeoutMs: deps.config.fetchTimeoutMs
+                });
+                if (!downloaded.ok || !downloaded.path) {
+                    continue;
+                }
+                const parsed = await parseTinyFromJar(downloaded.path);
+                if (parsed.size > 0) {
+                    return parsed;
+                }
+            }
+            catch {
+                // try the next candidate URL
+            }
+        }
+        return undefined;
+    };
+    let intermediaryParsed;
+    let yarnParsed;
     for (const { base, yarnCoordinates } of yarnCoordinatesByRepo) {
-        intermediaryUrls.push(`${base}/net/fabricmc/intermediary/${version}/intermediary-${version}-v2.jar`, `${base}/net/fabricmc/intermediary/${version}/intermediary-${version}.jar`);
+        if (!intermediaryParsed) {
+            intermediaryParsed = await tryUrls([
+                `${base}/net/fabricmc/intermediary/${version}/intermediary-${version}-v2.jar`,
+                `${base}/net/fabricmc/intermediary/${version}/intermediary-${version}.jar`
+            ]);
+        }
         for (const coordinate of yarnCoordinates) {
-            yarnUrls.push(`${base}/net/fabricmc/yarn/${coordinate}/yarn-${coordinate}-v2.jar`, `${base}/net/fabricmc/yarn/${coordinate}/yarn-${coordinate}.jar`);
+            if (yarnParsed) {
+                break;
+            }
+            yarnParsed = await tryUrls([
+                `${base}/net/fabricmc/yarn/${coordinate}/yarn-${coordinate}-v2.jar`,
+                `${base}/net/fabricmc/yarn/${coordinate}/yarn-${coordinate}.jar`
+            ]);
         }
-    }
-    const allUrls = [...intermediaryUrls, ...yarnUrls];
-    const parsedResults = await Promise.allSettled(allUrls.map(async (url) => {
-        const downloaded = await downloadToCache(url, defaultDownloadPath(deps.config.cacheDir, url), {
-            fetchFn: deps.fetchFn,
-            retries: deps.config.fetchRetries,
-            timeoutMs: deps.config.fetchTimeoutMs
-        });
-        if (!downloaded.ok || !downloaded.path) {
-            return undefined;
+        if (intermediaryParsed && yarnParsed) {
+            break;
         }
-        return parseTinyFromJar(downloaded.path);
-    }));
-    for (const result of parsedResults) {
-        if (result.status !== "fulfilled" || !result.value) {
+    }
+    for (const parsed of [intermediaryParsed, yarnParsed]) {
+        if (!parsed) {
             continue;
         }
-        for (const [key, index] of result.value.entries()) {
+        for (const [key, index] of parsed.entries()) {
             const existing = merged.get(key);
             if (!existing) {
                 merged.set(key, index);
@@ -98,7 +124,7 @@ export async function loadTinyPairsFromMaven(deps, version) {
     return {
         pairs: merged,
         warnings,
-        mappingArtifact: allUrls[0] ?? "maven:none"
+        mappingArtifact: attemptedUrls[0] ?? "maven:none"
     };
 }
 //# sourceMappingURL=tiny-maven.js.map

package/dist/mapping/lookup.d.ts

@@ -1,5 +1,5 @@
 import type { MappingSourcePriority, SourceMapping } from "../types.js";
-import type { CandidateAccumulator, DirectionIndex, LoadedGraph, MappingLookupSource, MappingSymbolRecord, MatchRankKey, PairKey, PairRecord } from "./internal-types.js";
+import type { CandidateAccumulator, DirectionIndex, ExactRecordIndex, LoadedGraph, MappingLookupSource, MappingSymbolRecord, MatchRankKey, PairKey, PairRecord } from "./internal-types.js";
 import { MAX_CANDIDATES } from "./internal-types.js";
 import type { ClassApiMatrixKind, DescriptorProjection, MappingLookupCandidate, ResolutionCandidate, SymbolQueryInput, SymbolReference } from "./types.js";
 export type { DescriptorProjection };
@@ -41,6 +41,17 @@ export declare function applyDisambiguationHints(candidates: MappingLookupCandid
 export declare function projectLookupCandidateDescriptor(candidate: MappingLookupCandidate, sourceDescriptor: string, targetDescriptor: string | undefined): MappingLookupCandidate;
 export declare function effectiveLoomSearchProjectPath(projectPath: string | undefined): string | undefined;
 export declare function collectTargetRecords(graph: LoadedGraph, targetMapping: SourceMapping): MappingSymbolRecord[];
+/**
+ * Lazily build (and memoize on the graph) an O(1) exact-lookup index for a
+ * target namespace. Classes key on their FQCN symbol (owner left empty) and are
+ * additionally indexed by simple name for the auto-class short-name path;
+ * fields/methods key on `kind|owner|name`.
+ */
+export declare function collectExactRecordIndex(graph: LoadedGraph, targetMapping: SourceMapping): ExactRecordIndex;
+export declare function lookupExactClassBySymbol(index: ExactRecordIndex, symbol: string): MappingSymbolRecord[];
+export declare function lookupExactMembersByOwner(index: ExactRecordIndex, owner: string): MappingSymbolRecord[];
+export declare function lookupExactClassBySimpleName(index: ExactRecordIndex, name: string): MappingSymbolRecord[];
+export declare function lookupExactMembers(index: ExactRecordIndex, kind: "field" | "method", owner: string, name: string): MappingSymbolRecord[];
 export declare function normalizeIncludedKinds(inputKinds: ClassApiMatrixKind[] | undefined): Set<ClassApiMatrixKind>;
 export declare function inferAmbiguityReasons(candidates: ResolutionCandidate[], usedMojangClientMappings: boolean): string[];
 export declare function clampCandidateLimit(limit: number | undefined): number;

package/dist/mapping/lookup.js

@@ -429,7 +429,59 @@ export function effectiveLoomSearchProjectPath(projectPath) {
     return normalizeOptionalProjectPath(projectPath) ?? normalizeOptionalProjectPath(process.cwd());
 }
 export function collectTargetRecords(graph, targetMapping) {
-    return [...(graph.recordsByTarget.get(targetMapping) ?? [])];
+    return graph.recordsByTarget.get(targetMapping) ?? [];
+}
+function exactRecordKey(kind, owner, name) {
+    return `${kind}|${owner}|${name}`;
+}
+/**
+ * Lazily build (and memoize on the graph) an O(1) exact-lookup index for a
+ * target namespace. Classes key on their FQCN symbol (owner left empty) and are
+ * additionally indexed by simple name for the auto-class short-name path;
+ * fields/methods key on `kind|owner|name`.
+ */
+export function collectExactRecordIndex(graph, targetMapping) {
+    const cached = graph.exactRecordIndex.get(targetMapping);
+    if (cached) {
+        return cached;
+    }
+    const byKey = new Map();
+    const classBySimpleName = new Map();
+    const membersByOwner = new Map();
+    const push = (map, key, record) => {
+        const bucket = map.get(key);
+        if (bucket) {
+            bucket.push(record);
+        }
+        else {
+            map.set(key, [record]);
+        }
+    };
+    for (const record of collectTargetRecords(graph, targetMapping)) {
+        if (record.kind === "class") {
+            push(byKey, exactRecordKey("class", "", record.symbol), record);
+            push(classBySimpleName, record.name, record);
+        }
+        else {
+            push(byKey, exactRecordKey(record.kind, record.owner ?? "", record.name), record);
+            push(membersByOwner, record.owner ?? "", record);
+        }
+    }
+    const index = { byKey, classBySimpleName, membersByOwner };
+    graph.exactRecordIndex.set(targetMapping, index);
+    return index;
+}
+export function lookupExactClassBySymbol(index, symbol) {
+    return index.byKey.get(exactRecordKey("class", "", symbol)) ?? [];
+}
+export function lookupExactMembersByOwner(index, owner) {
+    return index.membersByOwner.get(owner) ?? [];
+}
+export function lookupExactClassBySimpleName(index, name) {
+    return index.classBySimpleName.get(name) ?? [];
+}
+export function lookupExactMembers(index, kind, owner, name) {
+    return index.byKey.get(exactRecordKey(kind, owner, name)) ?? [];
 }
 export function normalizeIncludedKinds(inputKinds) {
     const normalized = new Set();

package/dist/mapping-service.js

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { mkdir, writeFile } from "node:fs/promises";
+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";
@@ -11,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";
@@ -375,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 {
@@ -510,18 +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 rowKindOrder = {
             class: 0,
             field: 1,
@@ -564,7 +571,8 @@ export class MappingService {
             className,
             classNameMapping,
             (input.includeKinds ?? []).join(","),
-            input.sourcePriority
+            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);
@@ -709,7 +717,9 @@ export class MappingService {
                 };
             })()
             : (() => {
-                const { record: queryRecord, querySymbol } = normalizeQuerySymbol(input, effectiveSignatureMode);
+                const { record: queryRecord, querySymbol } = normalizeQuerySymbol(input, effectiveSignatureMode, {
+                    allowShortClassName: input.kind === "class" && sourceMapping === "obfuscated"
+                });
                 return {
                     mode: "strict",
                     queryRecord,
@@ -730,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);
@@ -751,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.`);
@@ -764,16 +775,16 @@ 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 (effectiveSignatureMode === "name-only") {
             const status = methodCandidates.length === 1 ? "resolved" : methodCandidates.length > 1 ? "ambiguous" : "not_found";
@@ -1102,6 +1113,7 @@ 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.`
@@ -1116,6 +1128,7 @@ export class MappingService {
             adjacency: new Map(),
             pathCache: new Map(),
             recordsByTarget: new Map(),
+            exactRecordIndex: new Map(),
             classProjectionCache: new Map(),
             warnings: []
         };
@@ -1282,7 +1295,9 @@ 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;
 }
 /**

package/dist/mixin/annotation-validators.js

@@ -6,8 +6,26 @@ export function validateInjection(inj, targetMembers, targetNames, issues, resol
             continue;
         const methodNames = allMethodNames(members);
         // Strip owner prefix and JVM descriptor from the method reference
-        const methodName = extractMethodName(inj.method);
-        if (!methodNames.includes(methodName)) {
+        const rawMethodName = extractMethodName(inj.method);
+        // Strip a trailing target-selector quantifier (e.g. "tick*", "tick+", "tick{2,3}")
+        const quantifier = /(?:\*|\+|\{\d+(?:,\d+)?\})$/.exec(rawMethodName)?.[0];
+        const methodName = quantifier
+            ? rawMethodName.slice(0, rawMethodName.length - quantifier.length)
+            : rawMethodName;
+        if (quantifier && methodName === "") {
+            // Bare wildcard selector (e.g. method = "*") matches everything; unverifiable.
+            resolvedMembers.push({
+                annotation: `@${inj.annotation}`,
+                name: rawMethodName,
+                line: inj.line,
+                status: "skipped"
+            });
+            continue;
+        }
+        const matched = (quantifier === "*" || quantifier === "+")
+            ? methodNames.some((n) => n.startsWith(methodName))
+            : methodNames.includes(methodName);
+        if (!matched) {
             const suggestions = suggestSimilar(methodName, methodNames);
             const descriptor = extractMethodDescriptor(inj.method);
             const descriptorHint = descriptor ? ` (descriptor: ${descriptor})` : "";
@@ -46,7 +64,7 @@ export function validateInjection(inj, targetMembers, targetNames, issues, resol
             // Name matched. If the reference carries a JVM descriptor, require an
             // overload to match it; otherwise a wrong-signature target (e.g. tick(D)V
             // when only tick(I)V exists) is silently reported as resolved.
-            const refDescriptor = extractMethodDescriptor(inj.method);
+            const refDescriptor = quantifier ? undefined : extractMethodDescriptor(inj.method);
             const sameNameMembers = [...members.constructors, ...members.methods].filter((member) => member.name === methodName);
             if (refDescriptor &&
                 sameNameMembers.length > 0 &&

package/dist/mixin/parsed-validator.js

@@ -27,6 +27,7 @@ export function validateParsedMixin(parsed, targetMembers, warnings, provenance,
                     resolutionPath: "target-mapping-failed",
                     falsePositiveRisk: healthReport?.overallHealthy === false ? "high" : "medium"
                 });
+                addSkippedMembers(parsed, resolvedMembers);
             }
             else if (symbolExistsButSignatureFailed?.has(target.className)) {
                 // Symbol exists in mapping graph but getSignature failed — tool limitation, not code issue