@adhisang/minecraft-modding-mcp 7.0.0-rc.0 → 7.0.0-rc.2

package/dist/source/artifact-resolver.d.ts

@@ -2,6 +2,74 @@ import type { SourceService } from "../source-service.js";
 import type { ArtifactContentsSummary, ProbeMinecraftArtifactInput, ProbeMinecraftArtifactOutput, ResolveArtifactInput, ResolveArtifactOutput } from "../source-service.js";
 import type { AccessTransformerNamespace, ArtifactProvenance, ArtifactScope, ArtifactTargetKind, ResolvedSourceArtifact, RuntimeLoader, RuntimeValidationProvenance, SourceMapping } from "../types.js";
 import type { WorkspaceProjectLoader } from "../workspace-mapping-service.js";
+/**
+ * Does this artifactId, on its own, name the Minecraft runtime rather than a
+ * library that merely shares Minecraft's group?
+ *
+ * This is the rule itself, held in one place so the two ways an artifact can be
+ * named cannot drift apart. `coordinateNamesMinecraftRuntime` applies it to a
+ * parsed Maven coordinate; `extractVersionFromPath` in
+ * `minecraft-explorer-service.ts` applies it to the artifactId DIRECTORY of a jar
+ * sitting in a dependency store, which is all a `kind:"jar"` target ever offers.
+ * When those two disagreed, `net.minecraft:launchwrapper:1.12` was a library on
+ * the coordinate route and the Minecraft runtime on the path route.
+ */
+export declare function artifactIdNamesMinecraftRuntime(artifactId: string): boolean;
+/**
+ * Does this Maven coordinate name the Minecraft runtime itself?
+ *
+ * Only then does its version segment carry a real Minecraft version, and only then
+ * may a version or namespace derived from the artifact be read as Minecraft's.
+ * `net.minecraft:launchwrapper:1.12` is a real library Mojang publishes on
+ * libraries.minecraft.net: judging by group alone read it as the runtime, so its
+ * own release number was reported as a Minecraft version and a class miss inside it
+ * was blamed on Minecraft obfuscation.
+ *
+ * A coordinate that cannot be parsed is not shown to name the runtime, so it
+ * answers `false`. That matches what both call sites did with a parse failure
+ * before this helper existed: the resolver left its group unread and fell through
+ * to "not Minecraft", and `isDependencyLikeArtifact` treated it as a library.
+ */
+export declare function coordinateNamesMinecraftRuntime(coordinate: string): boolean;
+/**
+ * Does this artifact hold a third-party library rather than the Minecraft runtime?
+ *
+ * Callers use this to decide whether any Minecraft version derived from the
+ * artifact's jar path or resolver metadata may be believed, and whether a
+ * class-not-found miss may be blamed on Minecraft obfuscation.
+ *
+ * `provenance.dependencyResolution` alone cannot answer it. That marker is written
+ * only when the same `resolveArtifact` call handled a `kind:"dependency"` target,
+ * yet `synthesizeDependencyTarget` rewrites such a target into `{kind:"coordinate"}`
+ * BEFORE `buildProvenance` runs — so a dependency-route artifact and one reached by
+ * naming the same Maven coordinate directly persist an identical `target` and
+ * `resolvedFrom.coordinate`. Keyed off the marker, the question "is this a
+ * dependency?" was really answering "was it reached by a dependency target in this
+ * very call?", and a coordinate target — or a later reuse of the stored artifact by
+ * `artifactId` — got the vanilla answer for a dependency jar.
+ *
+ * The coordinate is route-invariant, so it decides instead, through the same
+ * `coordinateNamesMinecraftRuntime` the resolver's own obfuscation gate uses: a
+ * coordinate that does not name the Minecraft runtime names a library whose paths
+ * and version segment say nothing about Minecraft. Sharing the one helper is
+ * deliberate — the two questions are the same question asked in opposite polarity,
+ * and answering them differently is how `net.minecraft:launchwrapper` came to be
+ * read as the runtime on one side while being a library on the other.
+ *
+ * One limit remains, and it predates this predicate: an artifact reached by
+ * `kind:"jar"` records no coordinate at all, so it falls to the absent case and
+ * keeps the path-derived behaviour it has always had. The absent case is vanilla
+ * because that is the pre-existing default for the routes that record no coordinate
+ * — not because a vanilla artifact necessarily lacks one; resolving
+ * `net.minecraft:client:26.1` by coordinate does store it, and the runtime-name
+ * check is what classifies it. (`extractVersionFromPath` in
+ * `minecraft-explorer-service.ts` refuses on its own for a jar served out of a
+ * dependency cache, which is what covers the no-coordinate dependency jar.)
+ */
+export declare function isDependencyLikeArtifact(input: {
+    provenance?: ArtifactProvenance;
+    coordinate?: string;
+}): boolean;
 export type VersionSourceDiscovery = {
     searchedPaths: string[];
     candidateArtifacts: string[];
@@ -42,6 +110,16 @@ export type MappingFallbackSuggestion = {
     nextAction: string;
     _suggestedCallPrimaryDropped?: boolean;
 };
+/**
+ * Does this jar path look like it holds Minecraft itself?
+ *
+ * Loom stages Minecraft into maven-shaped local stores — its own `minecraftMaven`
+ * repository, and from there Gradle's dependency cache — so a path alone cannot be
+ * dismissed as a third-party dependency just because it sits in one. This is the
+ * override that keeps such a jar's version readable; see `extractVersionFromPath`
+ * in `minecraft-explorer-service.ts`.
+ */
+export declare function looksLikeMinecraftArtifactPath(path: string): boolean;
 export declare function hasExactVersionToken(path: string, version: string): boolean;
 /**
  * True when a path carries the NeoForge/Forge loader version that corresponds
@@ -66,12 +144,17 @@ export declare function hasLoaderRuntimeVersionToken(path: string, mcVersion: st
  */
 export declare function inferRuntimeJarMinecraftVersion(path: string): string | undefined;
 /**
- * Loader a runtime jar belongs to, read from its path.
+ * Loader a runtime jar belongs to, read from the tool-written part of its path.
  *
  * A Loom cache holds NeoForge-patched jars under a `/neoforge/` segment
  * (`caches/fabric-loom/1.21.10/neoforge/21.10.50-beta/minecraft-merged-mojang-at-patched.jar`).
  * Serving one of those to a Fabric workspace silently validated a Fabric access
- * widener against NeoForge bytecode, so the loader has to travel with the jar.
+ * widener against NeoForge bytecode, so the loader has to travel with the jar —
+ * which is why NeoForge is still asked first and still wins inside a Loom cache.
+ *
+ * Fabric is asked before Forge because its markers name a specific tool
+ * (`fabric-loom`, `loom-cache`) while Forge's are a bare `forge` token and the
+ * three letters `srg`: inside a Loom cache the specific marker is the true one.
  */
 export declare function inferRuntimeJarLoader(path: string): RuntimeLoader;
 /**
@@ -169,10 +252,21 @@ export declare function resolveBinaryFallbackArtifact(svc: SourceService, input:
     /** Forwarded from the caller; unset keeps the historical decompile-on-demand behaviour. */
     allowDecompile?: boolean;
 }): Promise<ResolvedSourceArtifact | undefined>;
+/**
+ * Describe what an artifact's indexed contents are.
+ *
+ * `sourceKind` is a derivation question — was the text produced by decompiling
+ * bytecode? — and only the persisted `isDecompiled` flag answers it. `origin`
+ * records provenance (where the bytes came from) and is deliberately not read:
+ * the two axes disagree in practice, most visibly for a Jar-in-Jar shell, whose
+ * row keeps origin "decompiled" while ingest clears the derivation flag. It
+ * stays in the input shape only because every caller already carries it
+ * alongside the fields that are read.
+ */
 export declare function buildArtifactContentsSummary(_svc: SourceService, input: {
     origin: ResolvedSourceArtifact["origin"];
     sourceJarPath?: string;
-    isDecompiled?: boolean;
+    isDecompiled: boolean;
     qualityFlags: string[];
 }): ArtifactContentsSummary;
 export declare function buildMappingFallbackSuggestedCall(svc: SourceService, args: {

package/dist/source/artifact-resolver.js

@@ -13,6 +13,121 @@ import { artifactIdForJar, resolveSourceTarget as resolveSourceTargetInternal }
 import { resolveTinyRemapperJar } from "../tiny-remapper-resolver.js";
 import { isUnobfuscatedVersion } from "../version-service.js";
 import { dedupeQualityFlags, normalizeMapping, normalizeOptionalString, normalizePathStyle } from "./shared-utils.js";
+/**
+ * The Maven group under which the Minecraft runtime artifact itself is published
+ * (`net.minecraft:client`, `net.minecraft:server`, the Loom merged jars).
+ *
+ * The group is necessary but NOT sufficient: Mojang also publishes ordinary
+ * libraries here, `net.minecraft:launchwrapper:1.12` being the long-standing one.
+ * Use `coordinateNamesMinecraftRuntime` rather than comparing against this
+ * constant directly.
+ */
+const MINECRAFT_ARTIFACT_GROUP_ID = "net.minecraft";
+/**
+ * ArtifactIds under MINECRAFT_ARTIFACT_GROUP_ID that name the runtime itself, as
+ * opposed to a library that merely shares the group. `client` and `server` are the
+ * published runtime jars; every Loom-staged jar this codebase recognizes elsewhere
+ * (`minecraft-merged`, `minecraft-common`, `minecraft-clientonly`,
+ * `minecraft-client`, `minecraft-server` — see `looksLikeMinecraftArtifactPath`)
+ * starts with `minecraft`, so that prefix covers them without having to enumerate
+ * Loom's naming.
+ */
+const MINECRAFT_RUNTIME_ARTIFACT_IDS = new Set(["client", "server"]);
+/**
+ * Does this artifactId, on its own, name the Minecraft runtime rather than a
+ * library that merely shares Minecraft's group?
+ *
+ * This is the rule itself, held in one place so the two ways an artifact can be
+ * named cannot drift apart. `coordinateNamesMinecraftRuntime` applies it to a
+ * parsed Maven coordinate; `extractVersionFromPath` in
+ * `minecraft-explorer-service.ts` applies it to the artifactId DIRECTORY of a jar
+ * sitting in a dependency store, which is all a `kind:"jar"` target ever offers.
+ * When those two disagreed, `net.minecraft:launchwrapper:1.12` was a library on
+ * the coordinate route and the Minecraft runtime on the path route.
+ */
+export function artifactIdNamesMinecraftRuntime(artifactId) {
+    const normalized = artifactId.trim().toLowerCase();
+    return MINECRAFT_RUNTIME_ARTIFACT_IDS.has(normalized) || normalized.startsWith("minecraft");
+}
+/**
+ * Does this Maven coordinate name the Minecraft runtime itself?
+ *
+ * Only then does its version segment carry a real Minecraft version, and only then
+ * may a version or namespace derived from the artifact be read as Minecraft's.
+ * `net.minecraft:launchwrapper:1.12` is a real library Mojang publishes on
+ * libraries.minecraft.net: judging by group alone read it as the runtime, so its
+ * own release number was reported as a Minecraft version and a class miss inside it
+ * was blamed on Minecraft obfuscation.
+ *
+ * A coordinate that cannot be parsed is not shown to name the runtime, so it
+ * answers `false`. That matches what both call sites did with a parse failure
+ * before this helper existed: the resolver left its group unread and fell through
+ * to "not Minecraft", and `isDependencyLikeArtifact` treated it as a library.
+ */
+export function coordinateNamesMinecraftRuntime(coordinate) {
+    let parsed;
+    try {
+        parsed = parseCoordinate(coordinate);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.groupId !== MINECRAFT_ARTIFACT_GROUP_ID) {
+        return false;
+    }
+    return artifactIdNamesMinecraftRuntime(parsed.artifactId);
+}
+/**
+ * Does this artifact hold a third-party library rather than the Minecraft runtime?
+ *
+ * Callers use this to decide whether any Minecraft version derived from the
+ * artifact's jar path or resolver metadata may be believed, and whether a
+ * class-not-found miss may be blamed on Minecraft obfuscation.
+ *
+ * `provenance.dependencyResolution` alone cannot answer it. That marker is written
+ * only when the same `resolveArtifact` call handled a `kind:"dependency"` target,
+ * yet `synthesizeDependencyTarget` rewrites such a target into `{kind:"coordinate"}`
+ * BEFORE `buildProvenance` runs — so a dependency-route artifact and one reached by
+ * naming the same Maven coordinate directly persist an identical `target` and
+ * `resolvedFrom.coordinate`. Keyed off the marker, the question "is this a
+ * dependency?" was really answering "was it reached by a dependency target in this
+ * very call?", and a coordinate target — or a later reuse of the stored artifact by
+ * `artifactId` — got the vanilla answer for a dependency jar.
+ *
+ * The coordinate is route-invariant, so it decides instead, through the same
+ * `coordinateNamesMinecraftRuntime` the resolver's own obfuscation gate uses: a
+ * coordinate that does not name the Minecraft runtime names a library whose paths
+ * and version segment say nothing about Minecraft. Sharing the one helper is
+ * deliberate — the two questions are the same question asked in opposite polarity,
+ * and answering them differently is how `net.minecraft:launchwrapper` came to be
+ * read as the runtime on one side while being a library on the other.
+ *
+ * One limit remains, and it predates this predicate: an artifact reached by
+ * `kind:"jar"` records no coordinate at all, so it falls to the absent case and
+ * keeps the path-derived behaviour it has always had. The absent case is vanilla
+ * because that is the pre-existing default for the routes that record no coordinate
+ * — not because a vanilla artifact necessarily lacks one; resolving
+ * `net.minecraft:client:26.1` by coordinate does store it, and the runtime-name
+ * check is what classifies it. (`extractVersionFromPath` in
+ * `minecraft-explorer-service.ts` refuses on its own for a jar served out of a
+ * dependency cache, which is what covers the no-coordinate dependency jar.)
+ */
+export function isDependencyLikeArtifact(input) {
+    if (input.provenance?.dependencyResolution != null) {
+        return true;
+    }
+    const coordinate = normalizeOptionalString(input.coordinate) ??
+        normalizeOptionalString(input.provenance?.resolvedFrom?.coordinate);
+    if (!coordinate) {
+        return false;
+    }
+    // Polarity: this predicate is TRUE for a library, so it is the negation of the
+    // runtime test. An unparseable coordinate answers `false` there and therefore
+    // `true` here — it cannot be shown to name the Minecraft runtime, so treat it as
+    // a dependency and suppress a Minecraft version we could not justify, rather than
+    // asserting one on the strength of a string we failed to read.
+    return !coordinateNamesMinecraftRuntime(coordinate);
+}
 const VERSION_TOKEN_REGEX_CACHE = new Map();
 const LOADER_VERSION_TOKEN_REGEX_CACHE = new Map();
 const MAX_HELPER_REGEX_CACHE = 128;
@@ -32,10 +147,16 @@ function escapeRegexLiteral(value) {
 function hasPartialNetMinecraftCoverage(qualityFlags) {
     return qualityFlags.includes("partial-source-no-net-minecraft");
 }
-function looksLikeMinecraftSourceArtifact(path, hasMinecraftNamespace) {
-    if (hasMinecraftNamespace) {
-        return true;
-    }
+/**
+ * Does this jar path look like it holds Minecraft itself?
+ *
+ * Loom stages Minecraft into maven-shaped local stores — its own `minecraftMaven`
+ * repository, and from there Gradle's dependency cache — so a path alone cannot be
+ * dismissed as a third-party dependency just because it sits in one. This is the
+ * override that keeps such a jar's version readable; see `extractVersionFromPath`
+ * in `minecraft-explorer-service.ts`.
+ */
+export function looksLikeMinecraftArtifactPath(path) {
     const normalizedPath = normalizePathStyle(path).toLowerCase();
     return (normalizedPath.includes("/minecraftmaven/") ||
         normalizedPath.includes("/net/minecraft/") ||
@@ -46,6 +167,9 @@ function looksLikeMinecraftSourceArtifact(path, hasMinecraftNamespace) {
         normalizedPath.includes("minecraft-client") ||
         normalizedPath.includes("minecraft-server"));
 }
+function looksLikeMinecraftSourceArtifact(path, hasMinecraftNamespace) {
+    return hasMinecraftNamespace || looksLikeMinecraftArtifactPath(path);
+}
 export function hasExactVersionToken(path, version) {
     const normalizedPath = normalizePathStyle(path).toLowerCase();
     const normalizedVersion = version.trim().toLowerCase();
@@ -96,24 +220,64 @@ export function inferRuntimeJarMinecraftVersion(path) {
     return RUNTIME_JAR_VERSION_REGEX.exec(normalizePathStyle(path))?.[1];
 }
 /**
- * Loader a runtime jar belongs to, read from its path.
+ * Segment that opens a directory tree a BUILD TOOL wrote: a dot-directory
+ * (`.gradle`, `.gradle-user-home`, `.m2`), Gradle's `caches` root, or a project
+ * `build` directory. Everything below the deepest such segment was laid out by a
+ * tool and names what it holds; everything above it is the user's own directory
+ * names and names nothing.
+ */
+const RUNTIME_JAR_LAYOUT_ROOT_RE = /^(?:\.[^/]*|caches|build)$/;
+/**
+ * The part of a runtime jar path that a build tool wrote: everything below the
+ * deepest layout root, or the bare file name when the path never enters one.
+ *
+ * Judged over the WHOLE path, an ancestor directory decided the loader — a
+ * Fabric workspace checked out under `~/dev/forge/` was served "forge", and
+ * `moddev-notes` or `srg-test` anywhere above the jar was enough to name a
+ * loader for an artifact that names none.
+ */
+function runtimeJarLayoutRelativePath(path) {
+    const segments = normalizePathStyle(path)
+        .toLowerCase()
+        .split("/")
+        .filter((segment) => segment.length > 0);
+    for (let index = segments.length - 2; index >= 0; index -= 1) {
+        if (RUNTIME_JAR_LAYOUT_ROOT_RE.test(segments[index] ?? "")) {
+            return segments.slice(index + 1).join("/");
+        }
+    }
+    return segments[segments.length - 1] ?? "";
+}
+/**
+ * Loader a runtime jar belongs to, read from the tool-written part of its path.
  *
  * A Loom cache holds NeoForge-patched jars under a `/neoforge/` segment
  * (`caches/fabric-loom/1.21.10/neoforge/21.10.50-beta/minecraft-merged-mojang-at-patched.jar`).
  * Serving one of those to a Fabric workspace silently validated a Fabric access
- * widener against NeoForge bytecode, so the loader has to travel with the jar.
+ * widener against NeoForge bytecode, so the loader has to travel with the jar —
+ * which is why NeoForge is still asked first and still wins inside a Loom cache.
+ *
+ * Fabric is asked before Forge because its markers name a specific tool
+ * (`fabric-loom`, `loom-cache`) while Forge's are a bare `forge` token and the
+ * three letters `srg`: inside a Loom cache the specific marker is the true one.
  */
 export function inferRuntimeJarLoader(path) {
-    const lower = normalizePathStyle(path).toLowerCase();
-    if (lower.includes("neoforge") || lower.includes("neoform") || lower.includes("moddev")) {
+    const layoutPath = runtimeJarLayoutRelativePath(path);
+    if (layoutPath.includes("neoforge") ||
+        layoutPath.includes("neoform") ||
+        layoutPath.includes("moddev")) {
         return "neoforge";
     }
-    if (/(^|[/\-_])forge([/\-_.]|$)/.test(lower) || lower.includes("forge_gradle") || lower.includes("srg")) {
-        return "forge";
-    }
-    if (lower.includes("fabric-loom") || lower.includes("loom-cache") || lower.includes("intermediary")) {
+    if (layoutPath.includes("fabric-loom") ||
+        layoutPath.includes("loom-cache") ||
+        layoutPath.includes("intermediary")) {
         return "fabric";
     }
+    if (/(^|[/\-_])forge([/\-_.]|$)/.test(layoutPath) ||
+        layoutPath.includes("forge_gradle") ||
+        layoutPath.includes("srg")) {
+        return "forge";
+    }
     return "unknown";
 }
 /**
@@ -1032,8 +1196,19 @@ async function computeBinaryRemapGate(svc, input) {
         warnings: baseline.warnings
     };
 }
+/**
+ * Describe what an artifact's indexed contents are.
+ *
+ * `sourceKind` is a derivation question — was the text produced by decompiling
+ * bytecode? — and only the persisted `isDecompiled` flag answers it. `origin`
+ * records provenance (where the bytes came from) and is deliberately not read:
+ * the two axes disagree in practice, most visibly for a Jar-in-Jar shell, whose
+ * row keeps origin "decompiled" while ingest clears the derivation flag. It
+ * stays in the input shape only because every caller already carries it
+ * alongside the fields that are read.
+ */
 export function buildArtifactContentsSummary(_svc, input) {
-    const sourceKind = input.isDecompiled || input.origin === "decompiled" || !normalizeOptionalString(input.sourceJarPath)
+    const sourceKind = input.isDecompiled || !normalizeOptionalString(input.sourceJarPath)
         ? "decompiled-binary"
         : "source-jar";
     const sourceCoverage = hasPartialNetMinecraftCoverage(input.qualityFlags) ? "partial" : "full";
@@ -1210,17 +1385,16 @@ export async function resolveArtifact(svc, input) {
         let resolvedTarget = { kind, value };
         let resolvedVersion;
         let versionSourceDiscovery;
-        let runtimeNamesUnobfuscated = false;
         if (kind === "version") {
             const versionJar = await svc.versionService.resolveVersionJar(value);
             resolvedVersion = versionJar.version;
-            runtimeNamesUnobfuscated = isUnobfuscatedVersion(resolvedVersion);
             resolvedTarget = {
                 kind: "jar",
                 value: versionJar.jarPath
             };
             warnings.push(`Resolved Minecraft ${versionJar.version} from ${versionJar.clientJarUrl}.`);
         }
+        let coordinateIsMinecraftRuntime = false;
         if (kind === "coordinate") {
             try {
                 resolvedVersion = parseCoordinate(value).version;
@@ -1228,15 +1402,32 @@ export async function resolveArtifact(svc, input) {
             catch {
                 // coordinate validity is validated by resolver
             }
+            // Swallows its own parse failure and answers false, which is what the
+            // unread group left behind here before.
+            coordinateIsMinecraftRuntime = coordinateNamesMinecraftRuntime(value);
         }
-        if (!runtimeNamesUnobfuscated && resolvedVersion && isUnobfuscatedVersion(resolvedVersion)) {
-            runtimeNamesUnobfuscated = true;
-        }
+        // `isUnobfuscatedVersion` answers "does this MINECRAFT version ship unobfuscated
+        // names in its runtime jar?", so it may only be asked about a string that really is
+        // a Minecraft version. A kind="version" target always carries one. A coordinate
+        // carries one only when it names the Minecraft runtime artifact itself
+        // (net.minecraft:client:26.1); for any other coordinate the version segment is a
+        // third-party library's own release number — including a library published under
+        // Minecraft's own group, such as net.minecraft:launchwrapper, which is why the
+        // group alone cannot answer this and `coordinateNamesMinecraftRuntime` checks the
+        // artifactId too. Without this gate a dependency such as org.jetbrains:annotations:26.0.2
+        // parses as an "unobfuscated Minecraft version" and short-circuits
+        // applyMappingPipeline into reporting mappingApplied="mojang" with no remap
+        // performed, no verification, and no dependency-mapping-unverified warning.
+        // A kind="dependency" target is excluded outright regardless of its group,
+        // because binary remap is force-disabled for it (see forceBinaryRemapDisabled
+        // below), so its mapping is never actually enforced either way.
+        const versionNamesMinecraft = kind === "version" ||
+            (kind === "coordinate" && !dependencyOrigin && coordinateIsMinecraftRuntime);
+        const minecraftVersion = versionNamesMinecraft ? resolvedVersion : undefined;
+        const runtimeNamesUnobfuscated = minecraftVersion !== undefined && isUnobfuscatedVersion(minecraftVersion);
         let effectiveMapping = mapping;
-        if ((mapping === "intermediary" || mapping === "yarn") &&
-            resolvedVersion &&
-            isUnobfuscatedVersion(resolvedVersion)) {
-            warnings.push(`Version ${resolvedVersion} is unobfuscated; ${mapping} mappings are not applicable. Using the obfuscated namespace label for the deobfuscated runtime names.`);
+        if ((mapping === "intermediary" || mapping === "yarn") && runtimeNamesUnobfuscated) {
+            warnings.push(`Version ${minecraftVersion} is unobfuscated; ${mapping} mappings are not applicable. Using the obfuscated namespace label for the deobfuscated runtime names.`);
             effectiveMapping = "obfuscated";
         }
         if (kind === "version" &&
@@ -1382,7 +1573,10 @@ export async function resolveArtifact(svc, input) {
             resolved.sourceJarPath === versionSourceDiscovery.selectedSourceJarPath) {
             provenance.companionSourceJars = versionSourceDiscovery.companionSourceJarPaths;
         }
-        if (dependencyOrigin && dependencyRequestedMapping && dependencyRequestedMapping !== "obfuscated") {
+        if (dependencyOrigin &&
+            dependencyRequestedMapping &&
+            dependencyRequestedMapping !== "obfuscated" &&
+            mappingDecision.qualityFlags.includes("dependency-mapping-unverified")) {
             const coord = resolved.coordinate ?? value;
             warnings.push(`Dependency artifact ${coord} mapping "${dependencyRequestedMapping}" is not enforced (binary remap is disabled for non-vanilla artifacts); the JAR is returned in its native namespace and mappingApplied is reported as "obfuscated" with qualityFlag "dependency-mapping-unverified". Caller must validate symbol availability.`);
         }
@@ -1393,7 +1587,17 @@ export async function resolveArtifact(svc, input) {
         resolved.requestedMapping = effectiveMapping;
         resolved.mappingApplied = mappingDecision.mappingApplied;
         resolved.provenance = provenance;
-        resolved.qualityFlags = [...mappingDecision.qualityFlags];
+        // MERGE, never assign. The mapping pipeline builds its list from an empty
+        // array and knows only what mapping did, so anything the resolver already
+        // observed about the artifact itself - "binary-jar-no-classes" is the first
+        // such flag - is invisible to it. Overwriting the list here would drop those
+        // observations before dedupe, before indexing, and before the response is
+        // built, so the caller would never learn what the resolver saw. Same shape
+        // as the binary-fallback path above.
+        resolved.qualityFlags = dedupeQualityFlags([
+            ...(resolved.qualityFlags ?? []),
+            ...mappingDecision.qualityFlags
+        ]);
         if (versionSourceDiscovery?.candidateArtifacts.length) {
             resolved.qualityFlags.push("source-jar-found");
         }

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

@@ -65,6 +65,21 @@ export declare function buildClassSourceNotFoundError(svc: SourceService, input:
     mappingApplied: SourceMapping;
     requestedMapping: SourceMapping;
     qualityFlags: string[];
+    /**
+     * The mapping the CALLER wrote in the request, undefined when they omitted it.
+     * Distinct from `requestedMapping`, which falls back to the artifact's own
+     * namespace: only the caller-supplied value can tell whether the obfuscated
+     * namespace hint would be re-asking for an argument that is already present.
+     */
+    callerSuppliedMapping?: SourceMapping;
+    /**
+     * Whether the REQUESTED artifact is a native dependency, as decided by
+     * `isDependencyLikeArtifact`. Such artifacts are handed
+     * `mappingApplied: "obfuscated"` by substitution rather than by being an
+     * obfuscated index, which the obfuscated namespace hint must not mistake for
+     * a missing mapping argument.
+     */
+    nativeDependency?: boolean;
     attemptedBinaryFallback: boolean;
     filePath?: string;
     targetKind?: string;