@adhisang/minecraft-modding-mcp 5.0.0 → 6.1.0

package/dist/source/class-source.js

@@ -5,10 +5,38 @@ import { ERROR_CODES, createError, isAppError } from "../errors.js";
 import * as artifactResolver from "./artifact-resolver.js";
 import * as classSourceHelpers from "./class-source-helpers.js";
 import { buildClassSourceSnippet } from "./class-source/snippet-builder.js";
-import { remapAndCountMembers, sliceMembersWithLimit, projectMembersForWire } from "./class-source/members-builder.js";
+import { remapAndCountMembers, sliceMembersWithLimit, projectMembersForWire, projectMembersByLevel } from "./class-source/members-builder.js";
+import { matchesMemberPattern } from "./member-pattern.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 +63,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) {
@@ -221,13 +240,15 @@ export function buildDecompiledFallback(svc, artifactId, lookupClassName, member
         if (!memberPattern) {
             return list;
         }
-        const lower = memberPattern.toLowerCase();
-        return list.filter((entry) => entry.name.toLowerCase().includes(lower));
+        return list.filter((entry) => matchesMemberPattern(entry.name, memberPattern));
     };
     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,31 @@ 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
+    };
+}
+/**
+ * Apply a member projection to the decompiled fallback so it honors the same
+ * `projection` contract as the bytecode members block. The fallback only carries
+ * names + source line + kind (no signatures), so any non-"full" level reduces to
+ * the member name (the array it lives in already conveys the kind). Keeps the
+ * full shape for the default "full" level.
+ */
+function projectDecompiledFallback(fallback, level) {
+    if (level === "full") {
+        return fallback;
+    }
+    const reduce = (member) => ({ name: member.name });
+    return {
+        constructors: fallback.constructors.map(reduce),
+        fields: fallback.fields.map(reduce),
+        methods: fallback.methods.map(reduce),
+        origin: fallback.origin
     };
 }
 // The class-like symbol kinds findClass returns. MUST stay in sync with the JS-side
@@ -444,7 +485,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 +502,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,11 +666,25 @@ 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 } : {})
             }
         })
         : undefined;
+    // Decompiled source text can use different method/accessor names than the jar
+    // the workspace actually compiles against (e.g. `getGameRenderState()` in the
+    // decompiled source vs `gameRenderState()` in the runtime jar). Flag it so
+    // callers verify names against get-class-members (bytecode-derived) before
+    // copying signatures out of this source.
+    if (activeOrigin === "decompiled") {
+        activeQualityFlags = dedupeQualityFlags([
+            ...activeQualityFlags,
+            "decompiled-source-signatures-unverified"
+        ]);
+        warnings.push("Source is decompiled: method/accessor names may differ from the jar the workspace "
+            + "compiles against. Confirm signatures with get-class-members (bytecode-derived) "
+            + "before copying names from this source.");
+    }
     return {
         className,
         mode,
@@ -746,6 +802,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 +810,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: {} })
             }
         });
     }
@@ -868,7 +922,8 @@ export async function getClassMembers(svc, input) {
     // Slim the wire member shape: hoist a shared ownerFqn, drop accessFlags, omit
     // isSynthetic:false, and drop FIELD jvmDescriptor unless includeDescriptors.
     // Internal SignatureMember arrays above stay intact.
-    const projectedMembers = projectMembersForWire({ constructors, fields, methods }, includeInherited, input.includeDescriptors ?? false);
+    const projection = input.projection ?? "full";
+    const projectedMembers = projectMembersByLevel(projectMembersForWire({ constructors, fields, methods }, includeInherited, input.includeDescriptors ?? false), projection);
     const truncated = sliced.truncated;
     const nextCursor = sliced.nextOffset != null ? encodeOffsetCursor(sliced.nextOffset, memberCursorContext) : undefined;
     const normalizedProvenance = provenance ??
@@ -886,7 +941,7 @@ export async function getClassMembers(svc, input) {
         const fallbackPattern = namespaceMismatch ? undefined : memberPattern;
         const sourceFallback = buildDecompiledFallback(svc, artifactId, lookupClassName, fallbackPattern, maxMembers);
         if (sourceFallback) {
-            decompiledFallback = sourceFallback.fallback;
+            decompiledFallback = projectDecompiledFallback(sourceFallback.fallback, projection);
             decompiledMemberCounts = sourceFallback.counts;
             fallbackQualityFlags = dedupeQualityFlags([
                 ...qualityFlags,
@@ -898,6 +953,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." — a 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/member-pattern.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Match a class-member name against a `memberPattern` filter.
+ *
+ * Matching is case-insensitive substring. A `|` splits the pattern into OR
+ * alternatives, so `"getStateForPlacement|canSurvive|setPlacedBy"` matches a
+ * name that contains ANY of those tokens. Before this, the pattern was matched
+ * as a single literal substring, so a piped pattern searched for a name
+ * containing a literal `|` and matched nothing — which made member listing
+ * return zero on large vanilla classes when callers used the natural OR syntax.
+ *
+ * Java member names never contain `|`, so treating `|` as OR never collides with
+ * a legitimate substring search. Empty or whitespace-only alternatives are
+ * dropped; a pattern with no usable alternative matches nothing (a non-empty
+ * filter that excludes everything), matching the prior empty-filter behavior.
+ */
+export declare function matchesMemberPattern(name: string, pattern: string): boolean;

package/dist/source/member-pattern.js

@@ -0,0 +1,27 @@
+/**
+ * Match a class-member name against a `memberPattern` filter.
+ *
+ * Matching is case-insensitive substring. A `|` splits the pattern into OR
+ * alternatives, so `"getStateForPlacement|canSurvive|setPlacedBy"` matches a
+ * name that contains ANY of those tokens. Before this, the pattern was matched
+ * as a single literal substring, so a piped pattern searched for a name
+ * containing a literal `|` and matched nothing — which made member listing
+ * return zero on large vanilla classes when callers used the natural OR syntax.
+ *
+ * Java member names never contain `|`, so treating `|` as OR never collides with
+ * a legitimate substring search. Empty or whitespace-only alternatives are
+ * dropped; a pattern with no usable alternative matches nothing (a non-empty
+ * filter that excludes everything), matching the prior empty-filter behavior.
+ */
+export function matchesMemberPattern(name, pattern) {
+    const alternatives = pattern
+        .split("|")
+        .map((part) => part.trim().toLowerCase())
+        .filter((part) => part.length > 0);
+    if (alternatives.length === 0) {
+        return false;
+    }
+    const lowerName = name.toLowerCase();
+    return alternatives.some((alt) => lowerName.includes(alt));
+}
+//# sourceMappingURL=member-pattern.js.map

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,

package/dist/source-service.d.ts

@@ -11,7 +11,7 @@ import * as indexer from "./source/indexer.js";
 import * as workspaceTarget from "./source/workspace-target.js";
 import * as validateMixinModule from "./source/validate-mixin.js";
 import * as artifactResolver from "./source/artifact-resolver.js";
-import type { WireMembersBlock } from "./source/class-source/members-builder.js";
+import type { MemberProjection, ProjectedMembersBlock } from "./source/class-source/members-builder.js";
 import { type StageEmitter } from "./stage-emitter.js";
 import { WorkspaceMappingService, type WorkspaceCompileMappingOutput } from "./workspace-mapping-service.js";
 import { type WorkspaceContextCache } from "./workspace-context-cache.js";
@@ -266,11 +266,15 @@ export type GetClassMembersInput = {
     strictVersion?: boolean;
     /** When true, keep jvmDescriptor on FIELD members (always kept on methods/constructors). */
     includeDescriptors?: boolean;
+    /** Narrow the per-member fields returned: "names" | "signatures" | "full" (default "full"). */
+    projection?: MemberProjection;
 };
 export type DecompiledMember = {
     name: string;
-    line: number;
-    kind: "constructor" | "field" | "method";
+    /** Source line of the declaration. Omitted under a non-"full" projection. */
+    line?: number;
+    /** Member kind. Omitted under a non-"full" projection (the array conveys it). */
+    kind?: "constructor" | "field" | "method";
 };
 export type DecompiledFallback = {
     constructors: DecompiledMember[];
@@ -281,7 +285,7 @@ export type DecompiledFallback = {
 export type GetClassMembersStatus = "ok" | "members_unavailable" | "partial";
 export type GetClassMembersOutput = {
     className: string;
-    members: WireMembersBlock;
+    members: ProjectedMembersBlock;
     counts: {
         constructors: number;
         fields: number;

package/dist/source-service.js

@@ -141,7 +141,15 @@ export class SourceService {
     }
     async checkSymbolExists(input) {
         const result = await this.mappingService.checkSymbolExists(input);
-        if (result.status !== "mapping_unavailable" ||
+        // On unobfuscated versions the mapping graph is empty, so the mapping service can
+        // only ever report symbols as missing. We then validate against runtime bytecode.
+        // Classes/fields surface as `mapping_unavailable` when the graph yields nothing, but
+        // a method query with a non-empty graph returns `not_found` (empty member lookup) —
+        // which previously skipped the runtime fallback and produced false negatives for
+        // methods that genuinely exist. Treat `not_found` methods as fallback-eligible.
+        const fallbackEligible = result.status === "mapping_unavailable" ||
+            (result.status === "not_found" && input.kind === "method");
+        if (!fallbackEligible ||
             !isUnobfuscatedVersion(input.version) ||
             (input.sourceMapping !== "mojang" && input.sourceMapping !== "obfuscated")) {
             return result;