@adhisang/minecraft-modding-mcp 7.0.0-rc.3 → 7.1.0

package/dist/source/class-source.js

@@ -3,12 +3,14 @@ import { isAbsolute, resolve as resolvePath } from "node:path";
 import { buildSuggestedCall } from "../build-suggested-call.js";
 import { ERROR_CODES, createError, isAppError } from "../errors.js";
 import * as artifactResolver from "./artifact-resolver.js";
+import { isUnobfuscatedIdentityPair } from "./lifecycle/mapping-helpers.js";
 import * as classSourceHelpers from "./class-source-helpers.js";
 import { buildClassSourceSnippet } from "./class-source/snippet-builder.js";
 import { remapAndCountMembers, sliceMembersWithLimit, projectMembersForWire, projectMembersByLevel } from "./class-source/members-builder.js";
 import { collectDidYouMeanCandidates } from "./did-you-mean.js";
 import { matchesMemberPattern } from "./member-pattern.js";
 import { findNestedJarClasses, resolveUniqueNestedJarForClass } from "./nested-jars.js";
+import { extractSymbolsFromSource } from "../symbols/symbol-extractor.js";
 import { buildPageContextKey, encodeOffsetCursor, resolveCursorOffset } from "../page-cursor.js";
 import { dedupeQualityFlags, inheritArtifactMapping, normalizeMapping, normalizeOptionalString, normalizePathStyle } from "./shared-utils.js";
 import { isUnobfuscatedVersion } from "../version-service.js";
@@ -79,12 +81,33 @@ function looksLikeDeobfuscatedClassName(value) {
 function obfuscatedNamespaceHint(className) {
     return `Artifact is indexed in obfuscated runtime names. Deobfuscated names like "${className}" usually require mapping="mojang" or a find-mapping lookup to obfuscated names.`;
 }
+/**
+ * The artifact's Minecraft version when its runtime ships unobfuscated (26.1+)
+ * names, else undefined. A native dependency's version is its own release number,
+ * not a Minecraft version, so it is never put to `isUnobfuscatedVersion` (the same
+ * rule as the `reconcileUnobfuscatedNamespace` call sites).
+ */
+function unobfuscatedMinecraftVersion(input) {
+    if (input.nativeDependency || !input.version || !isUnobfuscatedVersion(input.version)) {
+        return undefined;
+    }
+    return input.version;
+}
+/**
+ * Said where the obfuscated namespace hint would otherwise have been: on 26.1+
+ * the as-shipped names are the Mojang names, so no mapping choice finds another class.
+ */
+function unobfuscatedRuntimeNamesNote(version) {
+    return `Minecraft ${version} ships Mojang names at runtime, so retrying with a different mapping will not change the class names.`;
+}
 function hasPartialNetMinecraftCoverage(qualityFlags) {
     return qualityFlags.includes("partial-source-no-net-minecraft");
 }
 /**
- * Whether "this artifact is indexed in obfuscated names, ask for mapping=mojang"
- * is TRUE for this artifact, from the pieces of it the caller sees.
+ * Whether a miss has the shape "this artifact is indexed in obfuscated names, ask
+ * for mapping=mojang" answers, from the pieces of the artifact the caller sees.
+ * The claim can still be false on Minecraft 26.1+; `isObfuscatedNamespaceHintTrue`
+ * adds that gate.
  *
  * Two artifact kinds report `mappingApplied: "obfuscated"` without being an
  * obfuscated Minecraft index, and the hint is simply false for them:
@@ -98,22 +121,41 @@ function hasPartialNetMinecraftCoverage(qualityFlags) {
  * without these exclusions an ordinary library class such as "GameTest"
  * qualifies and the caller is told to remap a jar that was never obfuscated.
  */
-function isObfuscatedNamespaceHintTrue(input) {
+function isObfuscatedLabelMiss(input) {
     return (input.mappingApplied === "obfuscated" &&
         !input.nativeDependency &&
         !input.qualityFlags.includes("shell-jar") &&
         looksLikeDeobfuscatedClassName(input.className));
 }
-function shouldSuggestObfuscatedMapping(artifact, className) {
-    return isObfuscatedNamespaceHintTrue({
+/**
+ * `isObfuscatedLabelMiss` is the shape of the miss the hint answers; this adds
+ * the one fact that makes its claim false even then. A Minecraft 26.1+ artifact
+ * labelled "obfuscated" is indexed in the as-shipped names, which ARE Mojang
+ * names: telling the caller to ask for mapping="mojang" sends them round a
+ * retry that returns the same names.
+ */
+function isObfuscatedNamespaceHintTrue(input) {
+    return (isObfuscatedLabelMiss(input) &&
+        unobfuscatedMinecraftVersion({
+            version: input.minecraftVersion,
+            nativeDependency: input.nativeDependency
+        }) === undefined);
+}
+function describeArtifactForNamespaceHint(artifact, className) {
+    return {
         mappingApplied: artifact.mappingApplied,
         qualityFlags: artifact.qualityFlags,
         nativeDependency: artifactResolver.isDependencyLikeArtifact({
             provenance: artifact.provenance,
             coordinate: artifact.coordinate
         }),
-        className
-    });
+        className,
+        minecraftVersion: artifactResolver.inferVersionFromContext({
+            version: artifact.version,
+            provenance: artifact.provenance,
+            coordinate: artifact.coordinate
+        })
+    };
 }
 function classNameToClassPath(className) {
     const normalized = normalizePathStyle(className.trim()).replace(/\//g, ".");
@@ -148,10 +190,31 @@ export function resolveClassFilePath(svc, artifactId, className) {
     const expectedPrefix = lastSlash < 0 ? "" : classPath.slice(0, lastSlash + 1);
     return svc.filesRepo.findBestClassLookupPath(artifactId, [...candidates], normalizedClassName, simpleName, expectedPrefix);
 }
+/**
+ * The class-name translation behind `svc.resolveClassNameForLookup`, whose callers
+ * (the lifecycle tools) pass a Minecraft version, so `version` also keys the 26.1+
+ * identity shortcut.
+ */
 export async function resolveClassNameForLookup(svc, input) {
+    return resolveArtifactClassNameForLookup(svc, { ...input, minecraftVersion: input.version });
+}
+/**
+ * `resolveClassNameForLookup` for an artifact the caller named, whose `version`
+ * need not be a Minecraft version: a dependency artifact's is its own release
+ * number. `version` still drives the mapping lookup, exactly as before; only
+ * `minecraftVersion`, which must be a proven Minecraft version, may take the 26.1+
+ * identity shortcut.
+ */
+async function resolveArtifactClassNameForLookup(svc, input) {
     if (input.sourceMapping === input.targetMapping) {
         return input.className;
     }
+    // On 26.1+ the as-shipped ("obfuscated") names ARE the Mojang names and the
+    // mapping graph between them is empty by design, so the lookup can only miss
+    // and warn about a translation that is the identity.
+    if (isUnobfuscatedIdentityPair(input.minecraftVersion, input.sourceMapping, input.targetMapping)) {
+        return input.className;
+    }
     if (!input.version) {
         input.warnings.push(`Could not map class "${input.className}" from ${input.sourceMapping} to ${input.targetMapping} for ${input.context} because version is unavailable.`);
         return input.className;
@@ -176,6 +239,38 @@ export async function resolveClassNameForLookup(svc, input) {
     }
     return input.className;
 }
+/**
+ * The provenance as returned, carrying `unobfuscatedRuntime` whenever the artifact
+ * it describes is a Minecraft 26.1+ runtime. The resolver stamps the flag on every
+ * fresh resolve, but a row indexed before the flag existed is served warm and never
+ * rewritten, and a row with no provenance gets `buildFallbackProvenance`. Only the
+ * provenance's OWN recorded version counts - never a project-derived one - and a
+ * dependency-like provenance is excluded, so a library's release number is never
+ * read as a Minecraft version. A jar row that predates the in-jar proof records no
+ * version and stays unflagged until a resolve proves the jar again, which backfills
+ * the row (`backfillResolvedVersion` in the indexer).
+ */
+function withUnobfuscatedRuntimeFlag(provenance) {
+    if (provenance.unobfuscatedRuntime === true ||
+        provenance.nestedJar ||
+        artifactResolver.isDependencyLikeArtifact({ provenance })) {
+        return provenance;
+    }
+    // A persisted or stubbed object can be partial; with nothing recorded there is
+    // nothing to derive the flag from.
+    const partial = provenance;
+    if (!partial.resolvedFrom || !partial.target) {
+        return provenance;
+    }
+    const version = unobfuscatedMinecraftVersion({
+        version: artifactResolver.inferVersionFromContext({
+            provenance,
+            coordinate: partial.resolvedFrom.coordinate
+        }),
+        nativeDependency: false
+    });
+    return version ? { ...provenance, unobfuscatedRuntime: true } : provenance;
+}
 export function buildFallbackProvenance(svc, input) {
     const artifact = svc.getArtifact(input.artifactId);
     const fallbackTarget = artifact.version
@@ -240,7 +335,21 @@ export function buildClassSourceNotFoundError(svc, input) {
         // jar. Candidates from the artifact the caller did not name carry its id.
         didYouMean: unionDidYouMeanCandidates(svc, requestedArtifactId, input.artifactId, input.className)
     };
+    const unobfuscatedVersion = unobfuscatedMinecraftVersion({
+        version: input.version,
+        nativeDependency: input.nativeDependency === true
+    });
     let nextAction = `Use find-class to resolve the correct fully-qualified name for "${simpleName}".`;
+    // On 26.1+ there is no namespace to switch to, so the most useful thing to say
+    // first is the nearest class the index does hold.
+    const nearestCandidate = unobfuscatedVersion
+        ? details.didYouMean[0]
+        : undefined;
+    if (nearestCandidate) {
+        nextAction =
+            `Did you mean "${nearestCandidate.className}"? didYouMean lists near-miss classes from the index; ` +
+                `otherwise use find-class to resolve the correct fully-qualified name for "${simpleName}".`;
+    }
     let suggestionSpec = {
         tool: "find-class",
         params: { className: simpleName, artifactId: requestedArtifactId }
@@ -290,16 +399,26 @@ export function buildClassSourceNotFoundError(svc, input) {
     // imperative "Provide/Pass mapping", and the sentence is concatenated into
     // the same `nextAction` string as the find-class guidance, which is published
     // as a single hint that no mid-string excision can repair.
+    //
+    // A third gate lives inside `isObfuscatedNamespaceHintTrue`: on Minecraft 26.1+
+    // the claim is false, and the same miss gets a note that no mapping will help.
     const callerAskedForNonObfuscatedMapping = input.callerSuppliedMapping != null && input.callerSuppliedMapping !== "obfuscated";
-    if (!callerAskedForNonObfuscatedMapping &&
-        isObfuscatedNamespaceHintTrue({
-            mappingApplied: input.mappingApplied,
-            qualityFlags: input.qualityFlags,
-            nativeDependency: input.nativeDependency === true,
-            className: input.className
-        })) {
+    const namespaceHintInput = {
+        mappingApplied: input.mappingApplied,
+        qualityFlags: input.qualityFlags,
+        nativeDependency: input.nativeDependency === true,
+        className: input.className,
+        minecraftVersion: input.version
+    };
+    if (!callerAskedForNonObfuscatedMapping && isObfuscatedNamespaceHintTrue(namespaceHintInput)) {
         nextAction += ` ${obfuscatedNamespaceHint(input.className)}`;
     }
+    else if (!callerAskedForNonObfuscatedMapping &&
+        unobfuscatedVersion &&
+        !hasPartialNetMinecraftCoverage(input.qualityFlags) &&
+        isObfuscatedLabelMiss(namespaceHintInput)) {
+        nextAction += ` ${unobfuscatedRuntimeNamesNote(unobfuscatedVersion)}`;
+    }
     details.nextAction = nextAction;
     Object.assign(details, buildSuggestedCall(suggestionSpec));
     // Split-source workspaces can omit client-only classes from merged indexes;
@@ -407,6 +526,50 @@ function projectDecompiledFallback(fallback, level) {
 // 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"];
+/**
+ * Reconstruct the full nesting chain between a file's top-level type and a
+ * type declared two or more levels deeper inside it. The extractor stores
+ * only ONE qualifiedName per FILE (the top-level type), so naively
+ * concatenating `<topLevelFQN>.<symbolName>` is only correct for exactly one
+ * level of nesting — it silently drops every intermediate enclosing type.
+ *
+ * Walks the file's own type declarations from the top-level type downward,
+ * using brace-range containment to find which declaration directly encloses
+ * `targetLine` at each level, collecting each intermediate simple name.
+ *
+ * Returns the intermediate simple names (outermost first, target excluded)
+ * or undefined when the chain cannot be reconstructed — e.g. the file's
+ * content is unavailable — in which case the caller falls back to the
+ * single-level formula.
+ */
+function resolveNestedTypeChain(svc, artifactId, filePath, topSimpleName, targetLine) {
+    const fileRow = svc.filesRepo.getFileContent(artifactId, filePath);
+    if (!fileRow)
+        return undefined;
+    const lines = fileRow.content.split(/\r?\n/);
+    const fileSymbols = extractSymbolsFromSource(filePath, fileRow.content);
+    let currentBody = classSourceHelpers.computeBraceRange(lines, fileSymbols, topSimpleName);
+    if (!currentBody)
+        return undefined;
+    const chain = [];
+    // Bounded by the number of type symbols in the file; guards against ever
+    // looping on a malformed structure.
+    for (let step = 0; step <= fileSymbols.length; step += 1) {
+        const childRanges = classSourceHelpers.computeNestedTypeRanges(lines, fileSymbols, currentBody);
+        if (childRanges.some((range) => range.declarationLine === targetLine)) {
+            return chain;
+        }
+        const containingChild = childRanges.find((range) => range.declarationLine < targetLine && targetLine <= range.endLine);
+        if (!containingChild)
+            return undefined;
+        const childSymbol = fileSymbols.find((symbol) => symbol.line === containingChild.declarationLine);
+        if (!childSymbol)
+            return undefined;
+        chain.push(childSymbol.symbolName);
+        currentBody = containingChild;
+    }
+    return undefined;
+}
 export function findClass(svc, input) {
     const className = input.className.trim();
     if (!className) {
@@ -500,8 +663,18 @@ export function findClass(svc, input) {
         const enclosingQualifiedName = row.qualifiedName ?? row.filePath.replace(/\.java$/, "").replaceAll("/", ".");
         const enclosingSimpleName = enclosingQualifiedName.split(".").at(-1) ?? enclosingQualifiedName;
         const nested = enclosingSimpleName !== row.symbolName;
+        let qualifiedName = nested ? `${enclosingQualifiedName}.${row.symbolName}` : enclosingQualifiedName;
+        if (nested) {
+            // The formula above assumes exactly one level of nesting. When the type
+            // is nested two or more levels deep, reconstruct the real chain so the
+            // intermediate enclosing type(s) are not silently dropped.
+            const intermediateChain = resolveNestedTypeChain(svc, artifactId, row.filePath, enclosingSimpleName, row.line);
+            if (intermediateChain && intermediateChain.length > 0) {
+                qualifiedName = `${enclosingQualifiedName}.${[...intermediateChain, row.symbolName].join(".")}`;
+            }
+        }
         candidates.push({
-            qualifiedName: nested ? `${enclosingQualifiedName}.${row.symbolName}` : enclosingQualifiedName,
+            qualifiedName,
             filePath: row.filePath,
             line: row.line,
             symbolKind: row.symbolKind,
@@ -554,8 +727,23 @@ function finishFindClass(svc, input) {
             }
         }).suggestedCall;
     }
-    if (matches.length === 0 && shouldSuggestObfuscatedMapping(artifact, className)) {
-        warnings.push(`No exact class symbol matched "${className}". ${obfuscatedNamespaceHint(className)}`);
+    if (matches.length === 0) {
+        const hintInput = describeArtifactForNamespaceHint(artifact, className);
+        const unobfuscatedVersion = unobfuscatedMinecraftVersion({
+            version: hintInput.minecraftVersion,
+            nativeDependency: hintInput.nativeDependency
+        });
+        if (isObfuscatedNamespaceHintTrue(hintInput)) {
+            warnings.push(`No exact class symbol matched "${className}". ${obfuscatedNamespaceHint(className)}`);
+        }
+        else if (unobfuscatedVersion && isObfuscatedLabelMiss(hintInput)) {
+            const nearest = collectDidYouMeanCandidates(svc, artifactId, className)
+                .slice(0, 3)
+                .map((candidate) => `"${candidate.className}"`);
+            warnings.push(`No exact class symbol matched "${className}".` +
+                (nearest.length > 0 ? ` Did you mean ${nearest.join(", ")}?` : "") +
+                ` ${unobfuscatedRuntimeNamesNote(unobfuscatedVersion)}`);
+        }
     }
     return {
         matches,
@@ -702,6 +890,12 @@ export async function getClassSource(svc, input) {
     if (!artifactResolver.isDependencyLikeArtifact({ provenance, coordinate })) {
         mappingApplied = reconcileUnobfuscatedNamespace(version, requestedMapping, mappingApplied);
     }
+    // The same rule for the class-name lookup: its 26.1+ identity shortcut trusts only
+    // a Minecraft version, so a library's 26.x-shaped release number keeps the lookup
+    // (and its warnings) that any other library gets.
+    const minecraftVersion = artifactResolver.isDependencyLikeArtifact({ provenance, coordinate })
+        ? undefined
+        : version;
     let activeArtifactId = artifactId;
     let activeOrigin = origin;
     let activeIsDecompiled = isDecompiled;
@@ -802,9 +996,10 @@ export async function getClassSource(svc, input) {
         warnings.push(`Class "${className}" lives in nested jar "${match.entryName}" bundled by the shell jar; the lookup was redirected there automatically.`);
         return true;
     };
-    let activeLookupClassName = await svc.resolveClassNameForLookup({
+    let activeLookupClassName = await resolveArtifactClassNameForLookup(svc, {
         className,
         version,
+        minecraftVersion,
         sourceMapping: requestedMapping,
         targetMapping: activeMappingApplied,
         sourcePriority: input.sourcePriority,
@@ -817,9 +1012,10 @@ export async function getClassSource(svc, input) {
         filePath = resolveClassFilePath(svc, activeArtifactId, activeLookupClassName);
     }
     if (!filePath && (await tryBinaryFallback())) {
-        activeLookupClassName = await svc.resolveClassNameForLookup({
+        activeLookupClassName = await resolveArtifactClassNameForLookup(svc, {
             className,
             version,
+            minecraftVersion,
             sourceMapping: requestedMapping,
             targetMapping: activeMappingApplied,
             sourcePriority: input.sourcePriority,
@@ -861,9 +1057,10 @@ export async function getClassSource(svc, input) {
         }
     }
     if (!row && (await tryBinaryFallback())) {
-        activeLookupClassName = await svc.resolveClassNameForLookup({
+        activeLookupClassName = await resolveArtifactClassNameForLookup(svc, {
             className,
             version,
+            minecraftVersion,
             sourceMapping: requestedMapping,
             targetMapping: activeMappingApplied,
             sourcePriority: input.sourcePriority,
@@ -922,13 +1119,13 @@ export async function getClassSource(svc, input) {
         resolvedOutputFile = outputPath;
         sourceText = `[Written to ${outputPath}]`;
     }
-    const normalizedProvenance = activeProvenance ??
+    const normalizedProvenance = withUnobfuscatedRuntimeFlag(activeProvenance ??
         buildFallbackProvenance(svc, {
             artifactId: activeArtifactId,
             origin: activeOrigin,
             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
@@ -1097,10 +1294,14 @@ export async function getClassMembers(svc, input) {
     });
     // Gated on the same predicate as the source path above, and for the same
     // reason: a dependency's `version` is its own coordinate version, so the
-    // unobfuscated-runtime relabel must not reach it.
+    // unobfuscated-runtime relabel must not reach it - nor the 26.1+ identity
+    // shortcut of the class and member lookups below.
     if (!artifactResolver.isDependencyLikeArtifact({ provenance, coordinate })) {
         mappingApplied = reconcileUnobfuscatedNamespace(version, requestedMapping, mappingApplied);
     }
+    const minecraftVersion = artifactResolver.isDependencyLikeArtifact({ provenance, coordinate })
+        ? undefined
+        : version;
     if (requestedMapping !== "obfuscated" && !version) {
         throw createError({
             code: ERROR_CODES.MAPPING_NOT_APPLIED,
@@ -1167,9 +1368,10 @@ export async function getClassMembers(svc, input) {
             }
         });
     }
-    const lookupClassName = await svc.resolveClassNameForLookup({
+    const lookupClassName = await resolveArtifactClassNameForLookup(svc, {
         className,
         version,
+        minecraftVersion,
         sourceMapping: requestedMapping,
         targetMapping: mappingApplied,
         sourcePriority: input.sourcePriority,
@@ -1292,6 +1494,7 @@ export async function getClassMembers(svc, input) {
         signatureFields,
         signatureMethods,
         version,
+        minecraftVersion,
         mappingApplied,
         requestedMapping,
         sourcePriority: input.sourcePriority,
@@ -1324,13 +1527,13 @@ export async function getClassMembers(svc, input) {
     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 baseProvenance = provenance ??
+    const baseProvenance = withUnobfuscatedRuntimeFlag(provenance ??
         buildFallbackProvenance(svc, {
             artifactId,
             origin,
             requestedMapping,
             mappingApplied
-        });
+        }));
     const normalizedProvenance = nestedJarRedirect
         ? { ...baseProvenance, nestedJar: nestedJarRedirect }
         : baseProvenance;

package/dist/source/indexer.js

@@ -415,8 +415,11 @@ export async function ingestIfNeeded(svc, resolved) {
         if (resolved.artifactAlias && existing.alias !== resolved.artifactAlias) {
             svc.artifactsRepo.setAlias(resolved.artifactId, resolved.artifactAlias);
         }
-        svc.metrics.recordArtifactCacheHit();
         const touchedAt = new Date().toISOString();
+        if (!existing.version) {
+            backfillResolvedVersion(svc, resolved, touchedAt);
+        }
+        svc.metrics.recordArtifactCacheHit();
         svc.artifactsRepo.touchArtifact(resolved.artifactId, touchedAt);
         touchCacheMetrics(svc, resolved.artifactId, touchedAt);
         return;
@@ -444,6 +447,71 @@ export async function ingestIfNeeded(svc, resolved) {
         }
     }
 }
+/**
+ * Writes the version a warm resolve derived onto a stored row that records none,
+ * with the two provenance fields that follow from it.
+ *
+ * The artifactId is a content hash, so a row indexed before its version could be
+ * derived - a Minecraft 26.1+ runtime jar indexed before the in-jar proof existed -
+ * is served warm by every later resolve and never rewritten. resolve-artifact then
+ * reports the version while the row lacks it, and every lookup by artifactId reads
+ * the row: get-class-members refuses mapping "mojang" for want of a version, and a
+ * miss still gets the legacy "use mapping=mojang" hint.
+ *
+ * Only gaps are filled. A stored version is never replaced, and the row keeps the
+ * label, chain and target it was indexed under. Only a version the fresh provenance
+ * records as resolved from is written: resolve-artifact records the version the
+ * target itself names (version target, coordinate or in-jar proof), which describes
+ * these bytes, while the binary fallback of get-class-source re-ingests with a
+ * caller version that may come from the project's gradle.properties, under the
+ * stored provenance, so it never qualifies. The row is re-read in the same
+ * synchronous turn as the write, so a concurrent writer since `existing` was read
+ * is not overwritten.
+ * `upsertArtifact` is the repo's only writer for these columns; on an existing row
+ * it updates in place and leaves `created_at` and the file index alone.
+ */
+function backfillResolvedVersion(svc, resolved, timestamp) {
+    const version = resolved.version;
+    if (!version || resolved.provenance?.resolvedFrom?.version !== version) {
+        return;
+    }
+    // Only a proven Minecraft 26.1+ runtime qualifies. A library version recorded by a
+    // dependency resolve must never land on a row whose stored provenance does not mark
+    // it as a dependency, or later lookups would read that version as Minecraft's.
+    if (resolved.provenance?.unobfuscatedRuntime !== true) {
+        return;
+    }
+    const current = svc.artifactsRepo.getArtifact(resolved.artifactId);
+    if (!current || current.version) {
+        return;
+    }
+    svc.artifactsRepo.upsertArtifact({
+        artifactId: current.artifactId,
+        alias: current.alias,
+        origin: current.origin,
+        coordinate: current.coordinate,
+        version,
+        binaryJarPath: current.binaryJarPath,
+        sourceJarPath: current.sourceJarPath,
+        repoUrl: current.repoUrl,
+        requestedMapping: current.requestedMapping,
+        mappingApplied: current.mappingApplied,
+        provenance: current.provenance
+            ? {
+                ...current.provenance,
+                resolvedFrom: {
+                    ...current.provenance.resolvedFrom,
+                    version: current.provenance.resolvedFrom?.version ?? version
+                },
+                unobfuscatedRuntime: true
+            }
+            : undefined,
+        qualityFlags: current.qualityFlags,
+        artifactSignature: current.artifactSignature,
+        isDecompiled: current.isDecompiled,
+        timestamp
+    });
+}
 async function rebuildMissingArtifactIndex(svc, resolved, reason) {
     svc.metrics.recordArtifactCacheMiss();
     svc.metrics.recordReindex();

package/dist/source/lifecycle/mapping-helpers.d.ts

@@ -1,6 +1,16 @@
 import type { SignatureMember } from "../../minecraft-explorer-service.js";
 import type { SourceService } from "../../source-service.js";
 import type { MappingSourcePriority, SourceMapping } from "../../types.js";
+/**
+ * On unobfuscated versions (26.1+) the as-shipped ("obfuscated") names are the Mojang
+ * names, so obfuscated<->mojang is the identity. The mapping graph is empty there, so
+ * asking it would only report every member as unmapped.
+ *
+ * `minecraftVersion` must be a proven Minecraft version. A dependency
+ * artifact's version is its own release number (`annotations:26.0.2`), so callers
+ * serving one pass undefined and keep the mapping lookup it always had.
+ */
+export declare function isUnobfuscatedIdentityPair(minecraftVersion: string | undefined, sourceMapping: SourceMapping, targetMapping: SourceMapping): boolean;
 export declare function normalizeMapping(mapping: SourceMapping | undefined): SourceMapping;
 export declare function rejectLifecycleClassLikeInput(svc: SourceService, input: {
     symbol: string;
@@ -16,7 +26,16 @@ export declare function resolveToObfuscatedMemberName(svc: SourceService, name:
     name: string;
     descriptor?: string;
 }>;
-export declare function remapSignatureMembers(svc: SourceService, members: SignatureMember[], kind: "field" | "method", version: string, sourceMapping: SourceMapping, targetMapping: SourceMapping, sourcePriority: MappingSourcePriority | undefined, warnings: string[], projectPath?: string, gradleUserHome?: string): Promise<{
+export declare function remapSignatureMembers(svc: SourceService, members: SignatureMember[], kind: "field" | "method", version: string, sourceMapping: SourceMapping, targetMapping: SourceMapping, sourcePriority: MappingSourcePriority | undefined, warnings: string[], projectPath?: string, gradleUserHome?: string, 
+/**
+ * The Minecraft version the obfuscated<->mojang identity shortcut may trust.
+ * Defaults to `version`, which the lifecycle, validate-mixin and access-widener
+ * callers pass as a Minecraft version; get-class-members passes undefined for a
+ * dependency artifact, whose `version` is the library's own.
+ */
+identity?: {
+    minecraftVersion: string | undefined;
+}): Promise<{
     members: SignatureMember[];
     failedNames: Set<string>;
 }>;

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

@@ -1,6 +1,24 @@
 import { buildSuggestedCall } from "../../build-suggested-call.js";
 import { ERROR_CODES, createError } from "../../errors.js";
+import { isUnobfuscatedVersion } from "../../version-service.js";
 import { rebuildJavaSignature, remapJvmDescriptor } from "../descriptor-utils.js";
+/**
+ * On unobfuscated versions (26.1+) the as-shipped ("obfuscated") names are the Mojang
+ * names, so obfuscated<->mojang is the identity. The mapping graph is empty there, so
+ * asking it would only report every member as unmapped.
+ *
+ * `minecraftVersion` must be a proven Minecraft version. A dependency
+ * artifact's version is its own release number (`annotations:26.0.2`), so callers
+ * serving one pass undefined and keep the mapping lookup it always had.
+ */
+export function isUnobfuscatedIdentityPair(minecraftVersion, sourceMapping, targetMapping) {
+    const pair = new Set([sourceMapping, targetMapping]);
+    return (pair.size === 2 &&
+        pair.has("obfuscated") &&
+        pair.has("mojang") &&
+        minecraftVersion !== undefined &&
+        isUnobfuscatedVersion(minecraftVersion));
+}
 export function normalizeMapping(mapping) {
     if (mapping == null) {
         return "obfuscated";
@@ -87,7 +105,7 @@ export async function resolveToObfuscatedClassName(svc, className, version, mapp
     });
 }
 export async function resolveToObfuscatedMemberName(svc, name, ownerInSourceMapping, descriptor, kind, version, mapping, sourcePriority, warnings, gradleUserHome) {
-    if (mapping === "obfuscated") {
+    if (mapping === "obfuscated" || isUnobfuscatedIdentityPair(version, mapping, "obfuscated")) {
         return {
             name,
             descriptor: kind === "method" ? descriptor : undefined
@@ -167,9 +185,17 @@ export async function resolveToObfuscatedMemberName(svc, name, ownerInSourceMapp
         descriptor: kind === "method" ? descriptor : undefined
     };
 }
-export async function remapSignatureMembers(svc, members, kind, version, sourceMapping, targetMapping, sourcePriority, warnings, projectPath, gradleUserHome) {
+export async function remapSignatureMembers(svc, members, kind, version, sourceMapping, targetMapping, sourcePriority, warnings, projectPath, gradleUserHome, 
+/**
+ * The Minecraft version the obfuscated<->mojang identity shortcut may trust.
+ * Defaults to `version`, which the lifecycle, validate-mixin and access-widener
+ * callers pass as a Minecraft version; get-class-members passes undefined for a
+ * dependency artifact, whose `version` is the library's own.
+ */
+identity = { minecraftVersion: version }) {
     const failedNames = new Set();
-    if (sourceMapping === targetMapping) {
+    if (sourceMapping === targetMapping ||
+        isUnobfuscatedIdentityPair(identity.minecraftVersion, sourceMapping, targetMapping)) {
         return { members, failedNames };
     }
     const memberKeyToRemapped = new Map();

package/dist/source/lifecycle/runtime-check.d.ts

@@ -1,2 +1,27 @@
 import type { CheckSymbolExistsInput, CheckSymbolExistsOutput, SourceService } from "../../source-service.js";
+/**
+ * What a runtime-bytecode existence check established.
+ *
+ * `verified` is true when the runtime jar answered: the class loaded and the member
+ * lookup ran to completion, or the class was confirmed missing (CLASS_NOT_FOUND). It
+ * is false when the check could not be performed - a short class name, a member query
+ * without an owner, or a class that failed to load for any other reason (unreadable
+ * jar, malformed class file) - and `result` is then the fallback base with the
+ * explanatory warning appended, so it still carries the caller's own status.
+ */
+export interface UnobfuscatedRuntimeCheck {
+    verified: boolean;
+    result: CheckSymbolExistsOutput;
+}
+/**
+ * check-symbol-exists's runtime fallback: the result of `runUnobfuscatedRuntimeCheck`
+ * alone. Its callers keep the fallback base's status whenever the check could not be
+ * performed, so they need no `verified` flag.
+ */
 export declare function checkSymbolExistsInUnobfuscatedRuntime(svc: SourceService, input: CheckSymbolExistsInput, fallbackBase: CheckSymbolExistsOutput): Promise<CheckSymbolExistsOutput | undefined>;
+/**
+ * Checks a symbol against the Minecraft runtime jar of an unobfuscated version, whose
+ * names are the Mojang names. Undefined when the version or name is empty or the
+ * runtime jar cannot be resolved.
+ */
+export declare function runUnobfuscatedRuntimeCheck(svc: SourceService, input: CheckSymbolExistsInput, fallbackBase: CheckSymbolExistsOutput): Promise<UnobfuscatedRuntimeCheck | undefined>;