@adhisang/minecraft-modding-mcp 4.2.1 → 6.0.0

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 = [];
@@ -67,17 +68,73 @@ export function extractDecompiledMembers(className, filePath, content) {
     }
     return { constructors, fields, methods };
 }
-export function computeLineBraceDepths(lines) {
+/**
+ * Remove everything that must not count toward brace depth — line comments,
+ * (possibly multi-line) block comments, string literals, and char literals —
+ * in a single stateful pass so that block comments spanning lines and char
+ * literals like '{' / '}' never skew brace accounting. Line indices are
+ * preserved (one output entry per input line). Text blocks (""" … """) are not
+ * special-cased; they are vanishingly rare in decompiled output.
+ */
+function stripBraceNoise(lines) {
+    const out = new Array(lines.length);
+    let inBlockComment = false;
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i] ?? "";
+        let result = "";
+        let j = 0;
+        while (j < line.length) {
+            const ch = line[j];
+            const next = line[j + 1];
+            if (inBlockComment) {
+                if (ch === "*" && next === "/") {
+                    inBlockComment = false;
+                    j += 2;
+                }
+                else {
+                    j += 1;
+                }
+                continue;
+            }
+            if (ch === "/" && next === "/") {
+                break; // line comment: ignore the rest of the line
+            }
+            if (ch === "/" && next === "*") {
+                inBlockComment = true;
+                j += 2;
+                continue;
+            }
+            if (ch === '"' || ch === "'") {
+                const quote = ch;
+                j += 1;
+                while (j < line.length) {
+                    if (line[j] === "\\") {
+                        j += 2;
+                        continue;
+                    }
+                    if (line[j] === quote) {
+                        j += 1;
+                        break;
+                    }
+                    j += 1;
+                }
+                continue;
+            }
+            result += ch;
+            j += 1;
+        }
+        out[i] = result;
+    }
+    return out;
+}
+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 < lines.length; i += 1) {
+    for (let i = 0; i < stripped.length; i += 1) {
         // Entry depth for this line = depth observed before any brace on it.
         depths[i] = depth;
-        const stripped = (lines[i] ?? "")
-            .replace(/\/\/.*/g, "")
-            .replace(/"(?:\\.|[^"\\])*"/g, "\"\"")
-            .replace(/'(?:\\.|[^'\\])*'/g, "''");
-        for (const char of stripped) {
+        for (const char of stripped[i] ?? "") {
             if (char === "{") {
                 depth += 1;
             }
@@ -88,23 +145,23 @@ 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 = strippedLines ?? stripBraceNoise(lines);
     let depth = 0;
     let started = false;
-    for (let i = declarationLine - 1; i < lines.length; i += 1) {
-        const stripped = (lines[i] ?? "")
-            .replace(/\/\/.*/g, "")
-            .replace(/"(?:\\.|[^"\\])*"/g, "\"\"");
-        for (const char of stripped) {
+    for (let i = declarationLine - 1; i < stripped.length; i += 1) {
+        for (const char of stripped[i] ?? "") {
             if (char === "{") {
                 depth += 1;
                 started = true;
@@ -119,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"
@@ -132,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

@@ -5,9 +5,37 @@ 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 } from "./class-source/members-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;
@@ -34,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) {
@@ -226,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;
     }
@@ -250,13 +272,17 @@ 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
+// isTypeSymbol checks below; pushed down to SQL so non-type rows are never fetched.
+const TYPE_SYMBOL_KINDS = ["class", "interface", "enum", "record"];
 export function findClass(svc, input) {
     const className = input.className.trim();
     if (!className) {
@@ -278,12 +304,20 @@ export function findClass(svc, input) {
     const warnings = [];
     const isQualified = className.includes(".");
     if (isQualified) {
-        const classPath = className.replace(/\./g, "/");
+        // The innermost simple name (handles both dot- and $-separated inner types).
+        const simpleName = className.split(/[.$]/).at(-1) ?? className;
+        const directPath = `${classNameToClassPath(className)}.java`;
+        // The extractor stores ONE (outer) qualifiedName per file, so a nested type's
+        // FQCN never equals any stored qualifiedName and its synthetic file path
+        // (pkg/Outer/Inner.java) does not exist. resolveClassFilePath maps the FQCN —
+        // inner classes included — to the real outer file, which we match on.
+        const resolvedFilePath = resolveClassFilePath(svc, artifactId, className);
         const result = svc.symbolsRepo.findScopedSymbols({
             artifactId,
-            query: className.split(".").at(-1) ?? className,
+            query: simpleName,
             match: "exact",
-            limit: 5000
+            symbolKinds: TYPE_SYMBOL_KINDS,
+            limit: limit * 5
         });
         const matches = result.items
             .filter((row) => {
@@ -292,14 +326,22 @@ export function findClass(svc, input) {
             if (!isTypeSymbol)
                 return false;
             const rowQualified = row.qualifiedName ?? row.filePath.replace(/\.java$/, "").replaceAll("/", ".");
-            return rowQualified === className || row.filePath === `${classPath}.java`;
+            return (rowQualified === className ||
+                row.filePath === directPath ||
+                (resolvedFilePath != null && row.filePath === resolvedFilePath));
+        })
+            .map((row) => {
+            const rowQualified = row.qualifiedName ?? row.filePath.replace(/\.java$/, "").replaceAll("/", ".");
+            // For an inner-class match the stored qualifiedName is the outer type; the
+            // caller asked for the full nested FQCN, so report that.
+            const isInnerMatch = rowQualified !== className && row.filePath !== directPath;
+            return {
+                qualifiedName: isInnerMatch ? className : rowQualified,
+                filePath: row.filePath,
+                line: row.line,
+                symbolKind: row.symbolKind
+            };
         })
-            .map((row) => ({
-            qualifiedName: row.qualifiedName ?? row.filePath.replace(/\.java$/, "").replaceAll("/", "."),
-            filePath: row.filePath,
-            line: row.line,
-            symbolKind: row.symbolKind
-        }))
             .slice(0, limit);
         const partialVanillaLookup = hasPartialNetMinecraftCoverage(artifact.qualityFlags) && looksLikeDeobfuscatedClassName(className);
         const filteredMatches = partialVanillaLookup && matches.every((match) => !match.qualifiedName.startsWith("net.minecraft.") && !match.qualifiedName.startsWith("com.mojang."))
@@ -317,6 +359,7 @@ export function findClass(svc, input) {
         artifactId,
         query: className,
         match: "exact",
+        symbolKinds: TYPE_SYMBOL_KINDS,
         limit: limit * 5
     });
     const matches = [];
@@ -423,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;
@@ -440,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;
@@ -587,6 +631,27 @@ export async function getClassSource(svc, input) {
             requestedMapping,
             mappingApplied: activeMappingApplied
         });
+    const nextStartLine = snippet.nextStartLine;
+    // Continuation guidance: when output was truncated and was not redirected to
+    // a file, hand the caller the next line to read plus a replayable call that
+    // re-reads from the already-resolved artifact (no re-resolution needed).
+    // nextStartLine is only set for snippet/full mode, so `mode` here is never
+    // "metadata". The caller's original endLine window is preserved so the
+    // continuation never reads past the requested range.
+    const continuation = nextStartLine != null && !resolvedOutputFile
+        ? buildSuggestedCall({
+            tool: "get-class-source",
+            params: {
+                className,
+                target: { kind: "artifact", artifactId: activeArtifactId },
+                mode,
+                startLine: nextStartLine,
+                ...(input.endLine != null ? { endLine: input.endLine } : {}),
+                ...(maxLines != null ? { maxLines } : {}),
+                ...(input.maxChars != null ? { maxChars: input.maxChars } : {})
+            }
+        })
+        : undefined;
     return {
         className,
         mode,
@@ -598,6 +663,8 @@ export async function getClassSource(svc, input) {
         },
         truncated,
         ...(charsTruncated ? { charsTruncated } : {}),
+        ...(snippet.outOfRange ? { outOfRange: true } : {}),
+        ...(nextStartLine != null ? { nextStartLine } : {}),
         origin: activeOrigin,
         artifactId: activeArtifactId,
         requestedMapping,
@@ -611,6 +678,7 @@ export async function getClassSource(svc, input) {
             isDecompiled: activeOrigin === "decompiled",
             qualityFlags: activeQualityFlags
         }),
+        ...(continuation?.suggestedCall ? { suggestedCall: continuation.suggestedCall } : {}),
         ...(resolvedOutputFile ? { outputFile: resolvedOutputFile } : {}),
         warnings
     };
@@ -629,7 +697,7 @@ export async function getClassMembers(svc, input) {
     const includeInherited = input.includeInherited ?? false;
     const memberPattern = normalizeOptionalString(input.memberPattern);
     const parsedMaxMembers = normalizeStrictPositiveInt(input.maxMembers, "maxMembers");
-    const maxMembers = parsedMaxMembers == null ? 500 : Math.min(parsedMaxMembers, 5000);
+    const maxMembers = parsedMaxMembers == null ? 150 : Math.min(parsedMaxMembers, 5000);
     const normalizedArtifactId = normalizeOptionalString(input.artifactId);
     if (normalizedArtifactId && input.target) {
         throw createError({
@@ -701,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,
@@ -708,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: {} })
             }
         });
     }
@@ -759,7 +825,23 @@ export async function getClassMembers(svc, input) {
     }
     catch (error) {
         if (isAppError(error) && error.code === ERROR_CODES.CLASS_NOT_FOUND) {
-            throw error;
+            // Re-raise with the shared recovery shape (find-class/api-matrix
+            // suggestedCall, namespace + scope hints) instead of the sparse bytecode
+            // error, so members and source agree on CLASS_NOT_FOUND guidance.
+            throw buildClassSourceNotFoundError(svc, {
+                artifactId,
+                className,
+                lookupClassName,
+                mappingApplied,
+                requestedMapping,
+                qualityFlags,
+                attemptedBinaryFallback: true,
+                targetKind: input.target?.kind,
+                targetValue: input.target && "value" in input.target ? input.target.value : undefined,
+                scope: input.scope,
+                projectPath: input.projectPath,
+                version
+            });
         }
         binaryExtractionFailed = true;
         binaryExtractionFailureReason = error instanceof Error ? error.message : String(error);
@@ -787,11 +869,29 @@ export async function getClassMembers(svc, input) {
         warnings
     });
     const counts = remapped.counts;
-    const sliced = sliceMembersWithLimit(remapped, counts.total, maxMembers, warnings);
+    // Offset cursor over the flat [constructors, fields, methods] member sequence.
+    // The context key ties a cursor to this exact query so a stale cursor restarts.
+    const memberCursorContext = buildPageContextKey([
+        artifactId,
+        lookupClassName,
+        requestedMapping,
+        mappingApplied,
+        access,
+        includeSynthetic,
+        includeInherited,
+        memberPattern
+    ]);
+    const { offset: memberOffset, cursorIgnored: memberCursorIgnored } = resolveCursorOffset(input.cursor, memberCursorContext);
+    const sliced = sliceMembersWithLimit(remapped, counts.total, maxMembers, warnings, memberOffset);
     const constructors = sliced.constructors;
     const fields = sliced.fields;
     const methods = sliced.methods;
+    // 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 truncated = sliced.truncated;
+    const nextCursor = sliced.nextOffset != null ? encodeOffsetCursor(sliced.nextOffset, memberCursorContext) : undefined;
     const normalizedProvenance = provenance ??
         buildFallbackProvenance(svc, {
             artifactId,
@@ -819,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.`);
             }
@@ -843,7 +949,7 @@ export async function getClassMembers(svc, input) {
             suggestedCall = buildSuggestedCall({
                 tool: "get-class-source",
                 params: {
-                    target: { type: "artifact", artifactId },
+                    target: { kind: "artifact", artifactId },
                     className,
                     mode: "snippet",
                     mapping: requestedMapping
@@ -861,13 +967,11 @@ export async function getClassMembers(svc, input) {
     }
     return {
         className,
-        members: {
-            constructors,
-            fields,
-            methods
-        },
+        members: projectedMembers,
         counts,
         truncated,
+        ...(nextCursor ? { nextCursor } : {}),
+        ...(memberCursorIgnored ? { cursorIgnored: true } : {}),
         context: signatureContext,
         origin,
         artifactId,

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

@@ -43,8 +43,8 @@ export async function indexArtifact(svc, input) {
     }
     const artifact = svc.getArtifact(artifactId);
     const force = input.force ?? false;
-    const hasFiles = svc.filesRepo.listFiles(artifact.artifactId, { limit: 1 }).items.length > 0;
     const meta = svc.indexMetaRepo.get(artifact.artifactId);
+    const hasFiles = meta ? meta.filesCount > 0 : false;
     const expectedSignature = artifact.artifactSignature ?? fallbackArtifactSignature(artifact.artifactId);
     const reason = resolveIndexRebuildReason({
         force,
@@ -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"
                     }
                 });
@@ -291,8 +294,11 @@ export function getArtifact(svc, artifactId) {
 }
 export async function ingestIfNeeded(svc, resolved) {
     const existing = svc.artifactsRepo.getArtifact(resolved.artifactId);
-    const hasFiles = svc.filesRepo.listFiles(resolved.artifactId, { limit: 1 }).items.length > 0;
     const meta = svc.indexMetaRepo.get(resolved.artifactId);
+    // Derive hasFiles from meta instead of a separate listFiles probe: when meta is
+    // absent the reason is "missing_meta" regardless of hasFiles, and when present
+    // meta.filesCount is the authoritative count written alongside the file rows.
+    const hasFiles = meta ? meta.filesCount > 0 : false;
     const reason = resolveIndexRebuildReason({
         force: false,
         expectedSignature: resolved.artifactSignature,
@@ -333,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);
@@ -426,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);