@adhisang/minecraft-modding-mcp 5.0.0 → 6.0.0

package/dist/source/artifact-resolver.js

@@ -54,7 +54,7 @@ export function hasExactVersionToken(path, version) {
     // Avoid prefix false-positives like "1.21.1" matching "1.21.10".
     const cached = VERSION_TOKEN_REGEX_CACHE.get(normalizedVersion);
     const pattern = cached
-        ?? rememberCachedRegex(VERSION_TOKEN_REGEX_CACHE, normalizedVersion, new RegExp(`(^|[^0-9a-z])${escapeRegexLiteral(normalizedVersion)}([^0-9a-z]|$)`, "i"));
+        ?? rememberCachedRegex(VERSION_TOKEN_REGEX_CACHE, normalizedVersion, new RegExp(`(^|[^0-9a-z])${escapeRegexLiteral(normalizedVersion)}(?![0-9a-z]|\\.[0-9])`, "i"));
     return pattern.test(normalizedPath);
 }
 function inferMergedRuntimeNamespaceHint(path) {

package/dist/source/class-source/snippet-builder.js

@@ -53,6 +53,12 @@ export function buildClassSourceSnippet(input) {
         sourceText = sliceToMaxCharsSafe(sourceText, input.maxChars);
         charsTruncated = true;
         truncated = true;
+        if (input.mode !== "metadata") {
+            const survivingNewlines = (sourceText.match(/\n/g) ?? []).length;
+            returnedEnd = sourceText.endsWith("\n")
+                ? returnedStart + survivingNewlines - 1
+                : returnedStart + survivingNewlines;
+        }
     }
     let nextStartLine;
     // Metadata mode returns a synthesized outline, not a line window into the

package/dist/source/class-source-helpers.d.ts

@@ -9,16 +9,16 @@ export declare function extractDecompiledMembers(className: string, filePath: st
     fields: DecompiledMember[];
     methods: DecompiledMember[];
 };
-export declare function computeLineBraceDepths(lines: string[]): number[];
+export declare function computeLineBraceDepths(lines: string[], strippedLines?: string[]): number[];
 export declare function computeBraceRange(lines: string[], symbols: Array<{
     symbolKind: string;
     symbolName: string;
     line: number;
-}>, simpleName: string): {
+}>, simpleName: string, strippedLines?: string[]): {
     declarationLine: number;
     endLine: number;
 } | undefined;
-export declare function scanBraceRange(lines: string[], declarationLine: number): {
+export declare function scanBraceRange(lines: string[], declarationLine: number, strippedLines?: string[]): {
     declarationLine: number;
     endLine: number;
 };
@@ -28,7 +28,7 @@ export declare function computeNestedTypeRanges(lines: string[], symbols: Array<
 }>, outerBody: {
     declarationLine: number;
     endLine: number;
-}): Array<{
+}, strippedLines?: string[]): Array<{
     declarationLine: number;
     endLine: number;
 }>;

package/dist/source/class-source-helpers.js

@@ -30,13 +30,14 @@ export function extractDecompiledMembers(className, filePath, content) {
     const symbols = extractSymbolsFromSource(filePath, content);
     const simpleName = className.split(/[.$]/).at(-1) ?? className;
     const lines = content.split(/\r?\n/);
-    const body = computeBraceRange(lines, symbols, simpleName);
+    const stripped = stripBraceNoise(lines);
+    const body = computeBraceRange(lines, symbols, simpleName, stripped);
     if (!body) {
         return { constructors: [], fields: [], methods: [] };
     }
-    const depths = computeLineBraceDepths(lines);
+    const depths = computeLineBraceDepths(lines, stripped);
     const baseDepth = depths[body.declarationLine - 1] ?? 0;
-    const nestedRanges = computeNestedTypeRanges(lines, symbols, body);
+    const nestedRanges = computeNestedTypeRanges(lines, symbols, body, stripped);
     const constructors = [];
     const fields = [];
     const methods = [];
@@ -126,8 +127,8 @@ function stripBraceNoise(lines) {
     }
     return out;
 }
-export function computeLineBraceDepths(lines) {
-    const stripped = stripBraceNoise(lines);
+export function computeLineBraceDepths(lines, strippedLines) {
+    const stripped = strippedLines ?? stripBraceNoise(lines);
     const depths = new Array(lines.length).fill(0);
     let depth = 0;
     for (let i = 0; i < stripped.length; i += 1) {
@@ -144,19 +145,19 @@ export function computeLineBraceDepths(lines) {
     }
     return depths;
 }
-export function computeBraceRange(lines, symbols, simpleName) {
+export function computeBraceRange(lines, symbols, simpleName, strippedLines) {
     const classSymbol = symbols.find((symbol) => (symbol.symbolKind === "class" || symbol.symbolKind === "interface"
         || symbol.symbolKind === "enum" || symbol.symbolKind === "record")
         && symbol.symbolName === simpleName);
     if (!classSymbol) {
         return undefined;
     }
-    return scanBraceRange(lines, classSymbol.line);
+    return scanBraceRange(lines, classSymbol.line, strippedLines);
 }
-export function scanBraceRange(lines, declarationLine) {
+export function scanBraceRange(lines, declarationLine, strippedLines) {
     // Strip from the start of the file so multi-line block-comment state is correct
     // by the time we reach declarationLine; indices stay aligned with `lines`.
-    const stripped = stripBraceNoise(lines);
+    const stripped = strippedLines ?? stripBraceNoise(lines);
     let depth = 0;
     let started = false;
     for (let i = declarationLine - 1; i < stripped.length; i += 1) {
@@ -175,7 +176,7 @@ export function scanBraceRange(lines, declarationLine) {
     }
     return { declarationLine, endLine: lines.length };
 }
-export function computeNestedTypeRanges(lines, symbols, outerBody) {
+export function computeNestedTypeRanges(lines, symbols, outerBody, strippedLines) {
     const ranges = [];
     for (const candidate of symbols) {
         if (candidate.symbolKind !== "class" && candidate.symbolKind !== "interface"
@@ -188,7 +189,7 @@ export function computeNestedTypeRanges(lines, symbols, outerBody) {
         if (ranges.some((range) => candidate.line >= range.declarationLine && candidate.line <= range.endLine)) {
             continue;
         }
-        const nestedRange = scanBraceRange(lines, candidate.line);
+        const nestedRange = scanBraceRange(lines, candidate.line, strippedLines);
         ranges.push(nestedRange);
     }
     return ranges;

package/dist/source/class-source.d.ts

@@ -2,6 +2,24 @@ import { type AppError } from "../errors.js";
 import type { SourceService } from "../source-service.js";
 import type { DecompiledFallback, FindClassInput, FindClassOutput, GetClassMembersInput, GetClassMembersOutput, GetClassSourceInput, GetClassSourceOutput } from "../source-service.js";
 import type { ArtifactProvenance, ArtifactScope, MappingSourcePriority, ResolvedSourceArtifact, SourceMapping } from "../types.js";
+/**
+ * Unobfuscated Minecraft versions (26.1+) ship their runtime and decompiled source
+ * in deobfuscated (mojang) names directly — there is no real obfuscated namespace to
+ * map to. An artifact whose stored namespace label is "obfuscated" is therefore a
+ * mislabel for a mojang request: the bytes already carry mojang names.
+ *
+ * Without this reconciliation, requestedMapping="mojang" !== mappingApplied="obfuscated"
+ * triggers a cascade of doomed work: resolveClassNameForLookup attempts a mojang->obfuscated
+ * class remap, remapSignatureMembers tries to remap every member obfuscated->mojang and drops
+ * them all (counts.total===0), which forces a spurious decompiledFallback, disables
+ * memberPattern, and floods the response with one "Could not remap ..." warning per member.
+ *
+ * Collapsing mappingApplied to the requested mojang namespace makes the whole pipeline an
+ * identity no-op: members are returned from bytecode with correct mojang names, memberPattern
+ * applies, and the per-member warning flood disappears. This is the single highest-impact
+ * token-efficiency fix for unobfuscated versions.
+ */
+export declare function reconcileUnobfuscatedNamespace(version: string | undefined, requestedMapping: SourceMapping, mappingApplied: SourceMapping): SourceMapping;
 export declare function resolveClassFilePath(svc: SourceService, artifactId: string, className: string): string | undefined;
 export declare function resolveClassNameForLookup(svc: SourceService, input: {
     className: string;
@@ -37,6 +55,7 @@ export declare function buildClassSourceNotFoundError(_svc: SourceService, input
 export declare function buildDecompiledFallback(svc: SourceService, artifactId: string, lookupClassName: string, memberPattern: string | undefined, maxMembers: number): {
     fallback: DecompiledFallback;
     counts: NonNullable<GetClassMembersOutput["decompiledMemberCounts"]>;
+    truncated: boolean;
 } | undefined;
 export declare function findClass(svc: SourceService, input: FindClassInput): FindClassOutput;
 export declare function getClassSource(svc: SourceService, input: GetClassSourceInput): Promise<GetClassSourceOutput>;

package/dist/source/class-source.js

@@ -8,7 +8,34 @@ import { buildClassSourceSnippet } from "./class-source/snippet-builder.js";
 import { remapAndCountMembers, sliceMembersWithLimit, projectMembersForWire } from "./class-source/members-builder.js";
 import { buildPageContextKey, encodeOffsetCursor, resolveCursorOffset } from "../page-cursor.js";
 import { dedupeQualityFlags, normalizeMapping, normalizeOptionalString, normalizePathStyle } from "./shared-utils.js";
+import { isUnobfuscatedVersion } from "../version-service.js";
 const MEMBERS_STATUS_LEGACY = process.env.MEMBERS_STATUS_LEGACY === "1";
+/**
+ * Unobfuscated Minecraft versions (26.1+) ship their runtime and decompiled source
+ * in deobfuscated (mojang) names directly — there is no real obfuscated namespace to
+ * map to. An artifact whose stored namespace label is "obfuscated" is therefore a
+ * mislabel for a mojang request: the bytes already carry mojang names.
+ *
+ * Without this reconciliation, requestedMapping="mojang" !== mappingApplied="obfuscated"
+ * triggers a cascade of doomed work: resolveClassNameForLookup attempts a mojang->obfuscated
+ * class remap, remapSignatureMembers tries to remap every member obfuscated->mojang and drops
+ * them all (counts.total===0), which forces a spurious decompiledFallback, disables
+ * memberPattern, and floods the response with one "Could not remap ..." warning per member.
+ *
+ * Collapsing mappingApplied to the requested mojang namespace makes the whole pipeline an
+ * identity no-op: members are returned from bytecode with correct mojang names, memberPattern
+ * applies, and the per-member warning flood disappears. This is the single highest-impact
+ * token-efficiency fix for unobfuscated versions.
+ */
+export function reconcileUnobfuscatedNamespace(version, requestedMapping, mappingApplied) {
+    if (version &&
+        requestedMapping === "mojang" &&
+        mappingApplied === "obfuscated" &&
+        isUnobfuscatedVersion(version)) {
+        return "mojang";
+    }
+    return mappingApplied;
+}
 function normalizeStrictPositiveInt(value, field) {
     if (value == null) {
         return undefined;
@@ -35,15 +62,6 @@ function normalizeMemberAccess(access) {
         details: { access }
     });
 }
-function buildResolveArtifactParams(target, extra = {}) {
-    return {
-        target: {
-            kind: target.kind,
-            value: target.value
-        },
-        ...extra
-    };
-}
 function looksLikeDeobfuscatedClassName(value) {
     const trimmed = value.trim();
     if (!trimmed) {
@@ -227,7 +245,10 @@ export function buildDecompiledFallback(svc, artifactId, lookupClassName, member
     let constructors = filterByPattern(extracted.constructors);
     let fields = filterByPattern(extracted.fields);
     let methods = filterByPattern(extracted.methods);
-    const totalBefore = constructors.length + fields.length + methods.length;
+    const constructorsBefore = constructors.length;
+    const fieldsBefore = fields.length;
+    const methodsBefore = methods.length;
+    const totalBefore = constructorsBefore + fieldsBefore + methodsBefore;
     if (totalBefore === 0) {
         return undefined;
     }
@@ -251,11 +272,12 @@ export function buildDecompiledFallback(svc, artifactId, lookupClassName, member
             origin: "source-extracted"
         },
         counts: {
-            constructors: constructors.length,
-            fields: fields.length,
-            methods: methods.length,
-            total: constructors.length + fields.length + methods.length
-        }
+            constructors: constructorsBefore,
+            fields: fieldsBefore,
+            methods: methodsBefore,
+            total: totalBefore
+        },
+        truncated: totalBefore > maxMembers
     };
 }
 // The class-like symbol kinds findClass returns. MUST stay in sync with the JS-side
@@ -444,7 +466,7 @@ export async function getClassSource(svc, input) {
         const artifact = svc.getArtifact(artifactId);
         artifactId = artifact.artifactId;
         origin = artifact.origin;
-        requestedMapping = artifact.requestedMapping ?? requestedMapping;
+        requestedMapping = input.mapping != null ? requestedMapping : (artifact.requestedMapping ?? requestedMapping);
         mappingApplied = artifact.mappingApplied ?? requestedMapping;
         provenance = artifact.provenance;
         qualityFlags = artifact.qualityFlags;
@@ -461,6 +483,7 @@ export async function getClassSource(svc, input) {
         preferProjectVersion: input.preferProjectVersion,
         warnings
     });
+    mappingApplied = reconcileUnobfuscatedNamespace(version, requestedMapping, mappingApplied);
     let activeArtifactId = artifactId;
     let activeOrigin = origin;
     let activeProvenance = provenance;
@@ -624,7 +647,7 @@ export async function getClassSource(svc, input) {
                 mode,
                 startLine: nextStartLine,
                 ...(input.endLine != null ? { endLine: input.endLine } : {}),
-                ...(input.maxLines != null ? { maxLines: input.maxLines } : {}),
+                ...(maxLines != null ? { maxLines } : {}),
                 ...(input.maxChars != null ? { maxChars: input.maxChars } : {})
             }
         })
@@ -746,6 +769,7 @@ export async function getClassMembers(svc, input) {
         preferProjectVersion: input.preferProjectVersion,
         warnings
     });
+    mappingApplied = reconcileUnobfuscatedNamespace(version, requestedMapping, mappingApplied);
     if (requestedMapping !== "obfuscated" && !version) {
         throw createError({
             code: ERROR_CODES.MAPPING_NOT_APPLIED,
@@ -753,10 +777,7 @@ export async function getClassMembers(svc, input) {
             details: {
                 mapping: requestedMapping,
                 nextAction: "Resolve with target: { kind: \"version\", value: ... } or specify a versioned coordinate.",
-                ...buildSuggestedCall({
-                    tool: "resolve-artifact",
-                    params: buildResolveArtifactParams({ kind: "version", value: "latest" })
-                })
+                ...buildSuggestedCall({ tool: "list-versions", params: {} })
             }
         });
     }
@@ -898,6 +919,12 @@ export async function getClassMembers(svc, input) {
             warnings.push("Bytecode member enumeration returned zero; populated decompiledFallback from decompiled source. "
                 + "Descriptors and access modifiers are unavailable — use get-class-source for full details."
                 + namespaceNote);
+            if (sourceFallback.truncated) {
+                const returnedTotal = decompiledFallback.constructors.length
+                    + decompiledFallback.fields.length
+                    + decompiledFallback.methods.length;
+                warnings.push(`Member list was truncated to ${returnedTotal} entries (from ${sourceFallback.counts.total}).`);
+            }
             if (namespaceMismatch && memberPattern) {
                 warnings.push(`memberPattern="${memberPattern}" was not applied to decompiledFallback because the artifact namespace (${mappingApplied}) differs from the requested namespace (${requestedMapping}); filter the response client-side after mapping.`);
             }

package/dist/source/file-access.js

@@ -71,12 +71,13 @@ export async function listArtifactFiles(svc, input) {
         const artifact = svc.getArtifact(input.artifactId);
         const limit = clampLimit(input.limit, 200, 2000);
         const warnings = [];
+        const prefix = input.prefix === undefined ? undefined : normalizePathStyle(input.prefix);
         const page = svc.filesRepo.listFiles(artifact.artifactId, {
             limit,
             cursor: input.cursor,
-            prefix: input.prefix
+            prefix
         });
-        const normalizedPrefix = normalizeOptionalString(input.prefix);
+        const normalizedPrefix = normalizeOptionalString(prefix);
         if (normalizedPrefix &&
             page.items.length === 0 &&
             (normalizedPrefix.startsWith("assets/") || normalizedPrefix.startsWith("data/"))) {

package/dist/source/indexer.js

@@ -210,17 +210,20 @@ export async function buildRebuiltArtifactData(svc, resolved) {
         }
         catch (caughtError) {
             if (isAppError(caughtError) && caughtError.code === ERROR_CODES.DECOMPILER_FAILED) {
+                // Decompilation failed BEFORE the artifact was ever upserted, so there is no
+                // queryable artifact. Deliberately omit artifactId from the error: exposing the
+                // would-be id led callers to pass it to find-class/get-class-*, which then failed
+                // with "Artifact not found. Resolve context first." (B5 state inconsistency).
+                const priorDetails = { ...(caughtError.details ?? {}) };
+                delete priorDetails.artifactId;
                 throw createError({
                     code: ERROR_CODES.DECOMPILER_FAILED,
                     message: caughtError.message,
                     details: {
-                        ...(caughtError.details ?? {}),
-                        artifactId: resolved.artifactId,
+                        ...priorDetails,
                         binaryJarPath: resolved.binaryJarPath,
-                        producedJavaCount: typeof caughtError.details?.producedJavaCount === "number"
-                            ? caughtError.details.producedJavaCount
-                            : 0,
-                        nextAction: "Verify Java runtime and Vineflower availability, then retry. If available, prefer source-backed artifacts.",
+                        producedJavaCount: typeof priorDetails.producedJavaCount === "number" ? priorDetails.producedJavaCount : 0,
+                        nextAction: "Decompilation failed, so no artifact was created. Verify Java runtime and Vineflower availability, then retry; prefer source-backed artifacts when available.",
                         recommendedCommand: "echo $MCP_VINEFLOWER_JAR_PATH"
                     }
                 });
@@ -336,6 +339,13 @@ export async function ingestIfNeeded(svc, resolved) {
     const inflight = svc.state.inflightArtifactIngests.get(resolved.artifactId);
     if (inflight) {
         await inflight;
+        const transformChain = resolved.provenance?.transformChain ?? [];
+        if (transformChain.includes("binary-remap:obf->mojang") && resolved.binaryJarPath) {
+            const reconciledBinaryJarPath = await maybeRemapBinaryForMojang(svc, resolved);
+            if (reconciledBinaryJarPath !== resolved.binaryJarPath) {
+                resolved.binaryJarPath = reconciledBinaryJarPath;
+            }
+        }
         return;
     }
     const ingestPromise = rebuildMissingArtifactIndex(svc, resolved, reason);
@@ -429,9 +439,16 @@ export async function maybeRemapBinaryForMojang(svc, resolved, deps = defaultBin
     if (inflight) {
         return inflight;
     }
+    // When a prior index-artifact persisted the remapped jar back into the
+    // artifacts row, binaryJarPath already equals remappedJarPath. Remapping that
+    // missing/corrupt path onto itself would fail permanently, so re-resolve the
+    // original obfuscated client jar to recover from out-of-band cache loss.
+    const inputJar = binaryJarPath === remappedJarPath
+        ? (await svc.versionService.resolveVersionJar(resolved.version)).jarPath
+        : binaryJarPath;
     const remapPromise = runBinaryRemapWithDeps(svc, {
         version: resolved.version,
-        inputJar: binaryJarPath,
+        inputJar,
         remappedDir,
         remappedJarPath
     }, deps);

package/dist/source/lifecycle/mapping-helpers.js

@@ -25,6 +25,22 @@ function looksLikeClassSegment(name) {
     const trimmed = name.trim();
     return /^[A-Z_$]/.test(trimmed);
 }
+/**
+ * Collapse N per-member remap failures into a single warning line. Preserves the
+ * original "Could not remap" / "Remap failed for" prefix so downstream classifiers
+ * (e.g. REMAP_WARNING_RE in validate-mixin, warningDetails coding) still recognise it,
+ * while bounding the per-member flood to one line plus a short sample of names.
+ */
+function pushAggregatedRemapWarning(warnings, prefix, names, kind, sourceMapping, targetMapping) {
+    if (names.length === 0) {
+        return;
+    }
+    const unique = [...new Set(names)];
+    const sample = unique.slice(0, 3).join(", ");
+    const more = unique.length > 3 ? `, +${unique.length - 3} more` : "";
+    const plural = names.length === 1 ? "" : "s";
+    warnings.push(`${prefix} ${names.length} ${kind}${plural} from ${sourceMapping} to ${targetMapping} (${sample}${more}).`);
+}
 export function rejectLifecycleClassLikeInput(svc, input) {
     void svc;
     if (!looksLikeClassSegment(input.methodName)) {
@@ -234,6 +250,13 @@ export async function remapSignatureMembers(svc, members, kind, version, sourceM
         "resolveMethodMappingExact" in svc.mappingService &&
         typeof svc.mappingService.resolveMethodMappingExact === "function";
     const memberEntries = [...memberKeyToRemapped.entries()];
+    // Collect per-member remap failures and emit a SINGLE aggregated warning each
+    // after the loop instead of one line per member. On namespace mismatches a large
+    // class can fail to remap every one of its ~150 members, which previously flooded
+    // both warnings[] and the 1:1 warningDetails[] with hundreds of near-identical
+    // lines (the dominant token sink for these responses).
+    const unremappedNames = [];
+    const remapErrorNames = [];
     await Promise.all(memberEntries.map(async ([key, _sourceName]) => {
         const [ownerFqn, name, descriptor] = key.split("\0");
         try {
@@ -299,20 +322,22 @@ export async function remapSignatureMembers(svc, members, kind, version, sourceM
                     }
                 }
                 else {
-                    warnings.push(`Could not remap ${kind} "${name}" from ${sourceMapping} to ${targetMapping}.`);
+                    unremappedNames.push(name);
                     failedNames.add(name);
                 }
             }
             else {
-                warnings.push(`Could not remap ${kind} "${name}" from ${sourceMapping} to ${targetMapping}.`);
+                unremappedNames.push(name);
                 failedNames.add(name);
             }
         }
         catch {
-            warnings.push(`Remap failed for ${kind} "${name}" from ${sourceMapping} to ${targetMapping}.`);
+            remapErrorNames.push(name);
             failedNames.add(name);
         }
     }));
+    pushAggregatedRemapWarning(warnings, "Could not remap", unremappedNames, kind, sourceMapping, targetMapping);
+    pushAggregatedRemapWarning(warnings, "Remap failed for", remapErrorNames, kind, sourceMapping, targetMapping);
     const isField = kind === "field";
     return {
         members: members.map((member) => {

package/dist/source/lifecycle/runtime-check.js

@@ -1,3 +1,4 @@
+import { ERROR_CODES, isAppError } from "../../errors.js";
 export async function checkSymbolExistsInUnobfuscatedRuntime(svc, input, fallbackBase) {
     const version = input.version.trim();
     const name = input.name.trim();
@@ -50,16 +51,25 @@ export async function checkSymbolExistsInUnobfuscatedRuntime(svc, input, fallbac
         signature = await svc.explorerService.getSignature({
             fqn: targetClass,
             jarPath,
-            access: "all"
+            access: "all",
+            // Method existence is asked relative to the owner type, so inherited methods count:
+            // `level.getGameTime()` exists on Level even though it is declared on a supertype.
+            // Scoped to methods only: fields already resolved correctly without an inheritance
+            // walk, and including inherited fields would let a shadowed field name match twice
+            // and flip a previously-resolved field to "ambiguous".
+            includeInherited: input.kind === "method"
         });
     }
-    catch {
+    catch (error) {
+        const classMissing = isAppError(error) && error.code === ERROR_CODES.CLASS_NOT_FOUND;
         return {
             ...fallbackBase,
             querySymbol,
             warnings: [
                 ...fallbackBase.warnings,
-                `Version ${version} is unobfuscated; runtime bytecode lookup could not load class "${targetClass}".`
+                classMissing
+                    ? `Class "${targetClass}" was not found in the Minecraft ${version} runtime jar; it does not exist (or is not in this jar).`
+                    : `Version ${version} is unobfuscated; runtime bytecode lookup could not load class "${targetClass}".`
             ]
         };
     }
@@ -114,9 +124,13 @@ export async function checkSymbolExistsInUnobfuscatedRuntime(svc, input, fallbac
         });
     }
     const methodCandidates = signature.methods.filter((method) => method.name === name);
-    if (input.signatureMode === "name-only") {
-        if (methodCandidates.length !== 1) {
-            return buildUnresolved(methodCandidates.length > 1 ? "ambiguous" : "not_found");
+    const signatureMode = input.signatureMode ?? "name-only";
+    if (signatureMode === "name-only") {
+        // Existence semantics: any overload with this name means the method exists. Multiple
+        // overloads are not "ambiguous" for a name-only existence check — only zero matches
+        // is not_found. (Use signatureMode: "exact" with a descriptor to pin one overload.)
+        if (methodCandidates.length === 0) {
+            return buildUnresolved("not_found");
         }
         return buildResolved({
             kind: "method",

package/dist/source/search.js

@@ -65,11 +65,13 @@ export function buildGlobRegex(pattern) {
     while (i < pattern.length) {
         const ch = pattern[i];
         if (ch === "*" && pattern[i + 1] === "*") {
-            result += ".*";
-            i += 2;
-            if (pattern[i] === "/") {
-                result += "(?:/)?";
-                i += 1;
+            if (pattern[i + 2] === "/") {
+                result += "(?:.*/)?";
+                i += 3;
+            }
+            else {
+                result += ".*";
+                i += 2;
             }
         }
         else if (ch === "*") {
@@ -301,6 +303,9 @@ export async function searchClassSource(svc, input) {
                     searchWarnings.push(`queryNamespace=${input.queryNamespace}: translation failed (${caughtError instanceof Error ? caughtError.message : String(caughtError)}); running literal search instead.`);
                 }
             }
+            else if (intent === "symbol") {
+                searchWarnings.push(`queryNamespace=${input.queryNamespace} requires a fully-qualified class name for translation; running literal search in ${artifactMapping} instead. Resolve "${originalQuery}" to an FQCN with find-class or find-mapping first.`);
+            }
             else if (intent === "text" || intent === "path") {
                 searchWarnings.push(`queryNamespace=${input.queryNamespace} has no effect when intent="${intent}" — ${intent} search is a literal match against the artifact's ${artifactMapping} index. Use intent="symbol" for namespace translation.`);
             }
@@ -676,7 +681,9 @@ export function searchPathIntent(svc, artifactId, query, match, scope, regexPatt
 }
 export function findSymbolHits(svc, artifactId, query, match, scope, regexPattern) {
     if (match !== "regex") {
-        const filePathLike = scope?.fileGlob ? globToSqlLike(normalizePathStyle(scope.fileGlob)) : undefined;
+        const filePathLike = scope?.fileGlob && !scope.fileGlob.includes("**")
+            ? globToSqlLike(normalizePathStyle(scope.fileGlob))
+            : undefined;
         const scoped = svc.symbolsRepo.findScopedSymbols({
             artifactId,
             query,
@@ -688,8 +695,12 @@ export function findSymbolHits(svc, artifactId, query, match, scope, regexPatter
         });
         svc.metrics.recordSearchDbRoundtrip();
         svc.metrics.recordSearchRowsScanned(scoped.items.length);
+        const globFilter = scope?.fileGlob ? buildGlobRegex(normalizePathStyle(scope.fileGlob)) : undefined;
         const result = [];
         for (const symbol of scoped.items) {
+            if (globFilter && !globFilter.test(symbol.filePath)) {
+                continue;
+            }
             if (!isSymbolKind(symbol.symbolKind)) {
                 continue;
             }
@@ -705,12 +716,15 @@ export function findSymbolHits(svc, artifactId, query, match, scope, regexPatter
         }
         return result;
     }
-    const candidates = svc.symbolsRepo.listSymbolsForArtifact(artifactId, scope?.symbolKind);
+    // Stream rows instead of materializing every symbol: regex scans on large
+    // artifacts only keep matching rows in memory this way.
+    const candidates = svc.symbolsRepo.iterateSymbolsForArtifact(artifactId, scope?.symbolKind);
     svc.metrics.recordSearchDbRoundtrip();
-    svc.metrics.recordSearchRowsScanned(candidates.length);
+    let rowsScanned = 0;
     const result = [];
     const glob = scope?.fileGlob ? buildGlobRegex(normalizePathStyle(scope.fileGlob)) : undefined;
     for (const symbol of candidates) {
+        rowsScanned += 1;
         if (!checkPackagePrefix(symbol.filePath, scope?.packagePrefix)) {
             continue;
         }
@@ -732,6 +746,7 @@ export function findSymbolHits(svc, artifactId, query, match, scope, regexPatter
             matchIndex: index
         });
     }
+    svc.metrics.recordSearchRowsScanned(rowsScanned);
     return result;
 }
 export function indexedCandidateLimit(svc) {

package/dist/source/validate-mixin/pipeline/resolve.js

@@ -40,10 +40,22 @@ export async function runResolveStage(svc, ctx) {
                 scope: ctx.input.scope,
                 preferProjectVersion: false
             });
-            ctx.jarPath = ctx.resolvedArtifact.binaryJarPath ?? (await svc.versionService.resolveVersionJar(ctx.version)).jarPath;
             ctx.warnings.push(...ctx.resolvedArtifact.warnings);
-            ctx.mappingApplied = ctx.resolvedArtifact.mappingApplied;
-            ctx.signatureLookupMapping = ctx.resolvedArtifact.mappingApplied;
+            if (ctx.resolvedArtifact.binaryJarPath) {
+                ctx.jarPath = ctx.resolvedArtifact.binaryJarPath;
+                ctx.mappingApplied = ctx.resolvedArtifact.mappingApplied;
+                ctx.signatureLookupMapping = ctx.resolvedArtifact.mappingApplied;
+            }
+            else {
+                ctx.jarPath = (await svc.versionService.resolveVersionJar(ctx.version)).jarPath;
+                ctx.signatureLookupMapping = "obfuscated";
+                ctx.scopeFallback = {
+                    requested: ctx.input.scope,
+                    applied: "vanilla",
+                    reason: "Resolved artifact had no binary jar (sources only); falling back to vanilla client jar."
+                };
+                ctx.warnings.push(`Scope "${ctx.input.scope}" resolved without a binary jar; falling back to vanilla client jar.`);
+            }
             if (ctx.resolvedArtifact.version) {
                 ctx.version = ctx.resolvedArtifact.version;
             }
@@ -59,6 +71,14 @@ export async function runResolveStage(svc, ctx) {
         }
     }
     else {
+        if (ctx.input.scope && ctx.input.scope !== "vanilla") {
+            ctx.scopeFallback = {
+                requested: ctx.input.scope,
+                applied: "vanilla",
+                reason: "projectPath required for merged/loader scope; falling back to vanilla client jar."
+            };
+            ctx.warnings.push(`Scope "${ctx.input.scope}" requires projectPath; falling back to vanilla client jar.`);
+        }
         ctx.jarPath = (await svc.versionService.resolveVersionJar(ctx.version)).jarPath;
     }
     if (ctx.jarPath.includes("-sources.jar")) {

package/dist/source/workspace-target.js

@@ -37,6 +37,7 @@ export async function loadOrDetectWorkspaceContext(svc, projectPath) {
             value: loaderResult.loader
         });
     }
+    const latest = svc.workspaceContextCache.read(projectPath);
     const ctx = {
         projectPath,
         minecraftVersion,
@@ -44,7 +45,7 @@ export async function loadOrDetectWorkspaceContext(svc, projectPath) {
         loader: loaderResult?.resolved ? loaderResult.loader : undefined,
         detectedAt: Date.now(),
         evidence,
-        dependencyVersions: cached?.dependencyVersions ?? new Map(),
+        dependencyVersions: latest?.dependencyVersions ?? cached?.dependencyVersions ?? new Map(),
         partial: false
     };
     svc.workspaceContextCache.write(ctx);

package/dist/source-resolver.js

@@ -260,7 +260,7 @@ export async function resolveSourceTarget(input, options, explicitConfig) {
                     ? false
                     : download.statusCode !== 404 && isTransientFailure(download.statusCode);
                 sawRemoteRepoFailure = sawRemoteRepoFailure || transient;
-                if (hasNextAttempt && transient) {
+                if (hasNextAttempt && (transient || download.ok)) {
                     options.onRepoFailover?.({
                         stage: "source",
                         repoUrl: sourceUrl,
@@ -320,7 +320,7 @@ export async function resolveSourceTarget(input, options, explicitConfig) {
                     ? false
                     : downloaded.statusCode !== 404 && isTransientFailure(downloaded.statusCode);
                 sawRemoteRepoFailure = sawRemoteRepoFailure || transient;
-                if (hasNextAttempt && transient) {
+                if (hasNextAttempt && (transient || downloaded.ok)) {
                     options.onRepoFailover?.({
                         stage: "binary",
                         repoUrl: binaryUrl,