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

package/CHANGELOG.md

@@ -7,6 +7,49 @@ and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2
 
 ## [Unreleased]
 
+## [7.1.0] - 2026-09-19
+
+### Added
+
+- `batch-class-source` and `batch-class-members` accept `target: { "kind": "artifact", "artifactId": "..." }`, the same target `get-class-source` and `get-class-members` accept, so a batch can reuse an artifact that an earlier call already resolved instead of resolving it again from its jar, version, or coordinate. This target was previously rejected with `ERR_INVALID_INPUT`. With it, `summary.sharedArtifactProvenance` is omitted, and an unknown `artifactId` fails each entry with `ERR_SOURCE_NOT_FOUND` rather than failing the whole batch.
+- `compare-minecraft` with `task="migration-overview"` reports which libraries shipped with Minecraft itself were added or removed between the two versions, such as LWJGL's GLFW binding being replaced by SDL, which class and registry diffs do not show. At `detail: "standard"` or `"full"`, the new `migration.libraries` block lists added and removed libraries as `group:artifact:version` and counts libraries whose version changed; `summary.counts.librariesAdded` and `librariesRemoved` carry the same counts at every detail level. A version bump or a per-platform native jar of a library already present is not reported as an addition or removal. When the version details cannot be fetched, or not within 5 seconds, the block is left out with a warning and the rest of the result is unchanged.
+- `provenance.unobfuscatedRuntime: true` marks an artifact whose runtime ships Mojang names (Minecraft 26.1+): version targets, Minecraft runtime coordinates, and jar targets proven to be a 26.1+ runtime jar. `resolve-artifact`, `get-class-source`, `get-class-members`, and the batch tools' `sharedArtifactProvenance` carry it; `provenance` itself is returned only with `include: ["provenance"]` or a fuller `detail` level. `mappingApplied` still reports the mapping you asked for, so `"obfuscated"` on such an artifact means the names as shipped, which are already Mojang names.
+
+### Changed
+
+- `validate-project` with `task="project-summary"` infers an omitted `version` from the project's `gradle.properties` (`minecraft_version`, `mc_version`, or `minecraftVersion`) and names the inferred version in `warnings`; it previously returned `status: "blocked"`. To keep the previous behavior, pass `preferProjectVersion: false`: a call without `version` then returns `blocked`, and the retry suggestions of an invalid-input error keep that explicit `false`. When files are found but no version can be inferred, the blocked reply asks for an explicit `version` instead of suggesting the same call again.
+
+### Performance
+
+- The first tool call after the server starts no longer stalls on a full consistency check of the local cache database. The check on open now uses SQLite's `quick_check` instead of `integrity_check`: on a 3.6 GB cache it takes about 2 s instead of about 19 s. A damaged cache file is still detected at startup, backed up and rebuilt. Rarer damage that the lighter check misses can surface later during a tool call; a call that hits it directly now fails with `ERR_DB_FAILURE` and restart guidance instead of `ERR_INTERNAL`, and the next start runs the full `integrity_check`. If the server cannot schedule that check, the error explains how to reset the cache by hand. A call where the damage surfaces inside another step may still report that step's own error.
+
+### Fixed
+
+- `validate-project` with `task="project-summary"`: a run that finds no Mixin configs, access wideners, or access transformers now reports `Nothing to validate: …`, naming only the file kinds it searched, with a warning that nothing was validated, instead of "Validated 0 mixin config(s), 0 access widener(s), and 0 access transformer(s)." `status` stays `"ok"`.
+- Minecraft 26.x snapshot, pre-release and release-candidate ids such as `26.3-snapshot-6`, `26.2-pre-6`, `26.2-rc-2` and `26.1.2-rc-1` are recognized as unobfuscated. They were treated as obfuscated legacy versions, so `mapping: "mojang"` was refused on them, `intermediary` and `yarn` did not fall back to `obfuscated`, and symbol checks did not use the runtime jar. Previously only weekly ids such as `26w14a` and unhyphenated forms such as `26.1-rc1`, which Mojang does not publish, were recognized.
+- `mapping: "mojang"` is accepted on a `target.kind: "jar"` that points at a Minecraft 26.1+ runtime jar, such as a jar from the Loom cache; it was refused with `ERR_MAPPING_NOT_APPLIED` and a hint to switch to `obfuscated`. A jar counts as a 26.1+ runtime jar when it has a top-level `version.json` with a 26.1+ `id`, contains `net/minecraft/SharedConstants.class`, and has no `.java` sources. Such a jar reports that `id` as its version and falls back from `intermediary` or `yarn` to `obfuscated` like a version target. A jar indexed by an earlier release has its version recorded on its next resolve, after which calls by `artifactId` accept `mojang` as well.
+- On Minecraft 26.1+ artifacts, class-not-found errors from `get-class-source` and `get-class-members`, and `find-class` misses, lead with the nearest class-name suggestion instead of telling you to retry with `mapping="mojang"`. When `mapping: "mojang"` is refused on a jar that is not a proven runtime jar, the error explains that `mapping: "obfuscated"` reads the names as shipped, and in a 26.1+ project it no longer suggests repeating the refused request. Hints for 1.x versions are unchanged.
+- `resolve-workspace-symbol` and `analyze-symbol` with `task="workspace"` resolve symbols in a Minecraft 26.1+ Loom project that declares no `mappings` line by checking the name against the runtime jar; they returned `mapping_unavailable` (`partial` in `analyze-symbol`). A class that is not in the Minecraft jar returns `not_found`, and a lookup that could not be checked returns `mapping_unavailable` with the reason. A path without a Gradle build script behaves as before.
+- On Minecraft 26.1+, `compare-minecraft` with `task="class-diff"` (and `diff-class-signatures`) and `trace-symbol-lifecycle` with `mapping: "mojang"` no longer mark every member as unmapped with "Could not remap" or "Could not map" warnings.
+- `check-symbol-exists` on Minecraft 26.1+ finds constructors: a method query named `<init>` with an existing descriptor resolves instead of returning `not_found`.
+
+### Documentation
+
+- The tool reference documents a known issue: on Minecraft 26.1+, responses label the runtime's Mojang names `obfuscated`, for example `mappingApplied: "obfuscated"`, whenever a request omits `mapping` or asks for `obfuscated`. The label stays until a future major release corrects it. Until then, `provenance.unobfuscatedRuntime: true` marks an artifact whose names are Mojang names, and `mapping: "mojang"` returns the same names labelled `mojang`.
+
+## [7.0.0] - 2026-09-13
+
+### Fixed
+
+- Several more ways a fault during the stdio supervisor's own fault-recovery work could leave a request permanently unanswered, or answered twice, are closed. A `validate-project` request could be left marked as still running forever if an internal recovery step for an earlier fault on that same request itself failed, blocking every later `validate-project` call for the rest of the session; that is now cleared first. If a client re-sent `initialize` to a worker that was already ready and the supervisor then faulted while recovering from that duplicate handshake, other requests still in flight on the worker being replaced were not answered and could hang for the rest of the session; they are now answered before the worker is replaced. And a request taken from the internal queue whose own reply step then failed in a narrow way could be left with no reply at all, or, in a different case, answered a second, spurious time; exactly one reply is now produced either way. Each of these requires an internal fault that is not known to occur in current Node.js and has not been observed in production.
+- Two remaining internal call sites that build an error's logged description now use the same safe string conversion already used elsewhere for this reason, so a thrown value whose own string conversion itself throws can no longer slip past them either. Cosmetic; there is no known way to trigger it.
+- Four more ways a fault on the stdio connection to the worker process could leave a request unanswered are closed. A write error to the worker other than a broken pipe used to be logged and otherwise ignored, leaving the connection pointed at a worker nothing could send to again, so every request already sent to it — and every request sent afterward — hung for the rest of the session; that fault now retires the broken worker and starts a replacement, answering the stranded request along the way. If that same fault lands while a still-starting successor worker is replaying the client's `initialize` handshake, the client's `initialize` call now fails immediately instead of waiting silently across every later restart attempt. A successful reply to `initialize` could also be lost outright if writing it to the client failed at the same moment as the fallback log message the supervisor writes about that failure; both are now recovered from together. And once `initialize` completes, a client may legally reuse its request id for a later call; if the worker then exited before answering that reused id, it used to be mistaken for the already-finished `initialize` and silently dropped instead of receiving its own reply.
+- A large request sent in line-delimited framing right after a `Content-Length`-framed one was wrongly rejected as an oversized header, because the 8 KiB header-size ceiling kept applying even once the reader had already moved on to line framing; such a request is now accepted up to the ordinary frame-size limit. Separately, when an oversized line arrived without its terminating newline yet, discarding it did not also consume the rest of that same line once the newline did arrive; the tail could then be re-read as if it were a fresh, legitimate request of its own. That tail is now discarded along with the rest of the line it belongs to.
+- Deleting a downloaded-jar entry with `manage-cache` could destroy a different jar than the one that was listed, when another resolve finished writing a fresh copy to the same cache slot in between; the delete now verifies it is still removing the jar it originally listed. A delete that could not actually remove a file — for example because the cache directory is read-only — is no longer reported as successful; it now returns a warning and the entry is not counted as deleted. Checking a cached download's size no longer treats a permission error the same as a missing file; previously that silently triggered a fresh download instead of surfacing the actionable error.
+- `find-class` now resolves the correct fully qualified name for a class nested two or more levels inside another class. It previously dropped every enclosing type past the first level, producing a name that does not exist among the compiled classes, so a follow-up call using that name — reading its members or source, for example — failed with a spurious not-found error. A class nested exactly one level deep was already correct and is unaffected.
+- An unrecognized failure opening the artifact index database — for example the database being locked or the disk being full — is now reported as the documented database-failure error instead of escaping unclassified. Previously only a failure already recognized as an I/O problem, a schema mismatch, or corruption was reported that way.
+- Loading a Yarn/Tiny mapping file from a Maven-hosted jar is now bounded the same way nested-jar and download extraction already are. A `.tiny` entry inside such a jar could previously be decompressed in full with no size limit, so a small, highly compressed entry could expand to multiple gigabytes and exhaust memory before mapping parsing ever started.
+
 ## [7.0.0-rc.3] - 2026-09-07
 
 ### Changed

package/README.md

@@ -170,7 +170,8 @@ These notes cover high-frequency decisions during onboarding. For the full pitfa
 - `trace-symbol-lifecycle` expects `Class.method` in `symbol`. Keep exact overload matching in the separate `descriptor` field.
 - For unobfuscated releases such as `26.1+`, `check-symbol-exists` and `analyze-symbol task="exists"` validate `mojang` lookups against runtime bytecode when no mapping graph exists, and return `mapping_unavailable` when the runtime JAR itself is unreachable.
 - `analyze-mod` and `validate-project` require structured `subject` objects and canonical `include` groups; stale string-subject or domain-include payloads return `ERR_INVALID_INPUT` with a retryable `suggestedCall`.
-- `validate-project task="project-summary"` propagates `preferProjectVersion=true` across discovered Mixin, Access Widener, and Access Transformer checks. If no version can be resolved from the request or `gradle.properties`, the summary returns recovery guidance instead of guessing.
+- `validate-project task="project-summary"` infers an omitted `version` from `gradle.properties` and names the inferred version in `warnings`; pass `preferProjectVersion: false` to turn inference off, in which case a call without `version` returns `status: "blocked"`. The resolved version is passed to every discovered Mixin, Access Widener, and Access Transformer check. If files were discovered but no version can be inferred, the summary returns `status: "blocked"` with a retry that asks for an explicit `version` instead of guessing.
+- When `validate-project task="project-summary"` discovers no files, `status` stays `"ok"` but the headline reads `Nothing to validate: ...` and `warnings` states that nothing was validated, so an `"ok"` status alone does not mean any file passed.
 - `validate-mixin` and `validate-project` keep `mapping-health` lightweight for `obfuscated` and `mojang` validation, avoiding full Tiny mapping graph loads unless `intermediary` or `yarn` namespaces are requested.
 - `validate-project task="project-summary"` uses a lightweight artifact probe for `tasks["minecraft.artifact.resolved"]`; it does not decompile Minecraft or rebuild the source index just to report per-probe status. It does read the runtime jar's bytes to derive the `artifactId` it reports, and repeat probes of the same jar in one process reuse that digest. Set `VALIDATE_PROJECT_TASKS_OFF=1` to omit the additive `tasks` field.
 - `validate-project` has a supervisor-owned end-to-end deadline of 120 seconds, including queue time. Set `MCP_VALIDATE_PROJECT_TIMEOUT_MS` to an ASCII-decimal value from `10000` through `600000` to override it. A timeout returns `ERR_TOOL_TIMEOUT`; a running timeout restarts the isolated worker before queued calls resume, while a queue timeout leaves the current worker untouched.
@@ -301,7 +302,7 @@ Tools for browsing Minecraft versions, resolving source artifacts, and reading o
 
 `find-class` accepts either an `artifactId` or the shared object `target` shape. For a workspace-relative dependency, pass `target: { kind: "dependency", group, name, versionFromProject: true }` with top-level `projectPath`. Fabric-style umbrella JARs are searched through their nested `.class` inventories; a top-level class match can then be passed to `get-class-source` or `get-class-members`, which resolve the containing nested JAR. Dotted inner-class matches are also readable through `get-class-source`. An empty result still means that the requested class name is absent from the resolved dependency version.
 
-For unobfuscated releases such as `26.1+`, `mapping="mojang"` uses the runtime/decompile path directly and skips Loom source-jar discovery, while `intermediary` and `yarn` fall back to `obfuscated` with a warning.
+For unobfuscated releases such as `26.1+`, `obfuscated` names the runtime jar's names as shipped, which are already Mojang names: both `obfuscated` and `mojang` are accepted, `mappingApplied` reports the label you asked for, and `provenance.unobfuscatedRuntime: true` marks the artifact. `mapping="mojang"` uses the runtime/decompile path directly and skips Loom source-jar discovery, while `intermediary` and `yarn` fall back to `obfuscated` with a warning. This applies to version targets, Minecraft runtime coordinates, and JAR targets whose own contents (a top-level `version.json` with a 26.1+ `id`, `net/minecraft/SharedConstants.class`, and no `.java` sources) prove a 26.1+ Minecraft runtime jar; see [docs/tool-reference.md → Lookup Rules](docs/tool-reference.md#lookup-rules). Labelling these Mojang names `obfuscated` is a known issue, kept unchanged for compatibility until a future major release corrects it; see [docs/tool-reference.md → Known issue: obfuscated label on unobfuscated runtimes](docs/tool-reference.md#known-issue-obfuscated-label-on-unobfuscated-runtimes).
 
 ### Version Comparison & Symbol Tracking
 

package/dist/cache-registry.d.ts

@@ -42,6 +42,22 @@ type CacheEntryPage = {
  * while still allowing major.minor sweeps where "1.21" matches "1.21.4".
  */
 export declare function pathContainsVersion(path: string, version: string): boolean;
+/**
+ * The identity `deleteEntries` captures for a downloads-cache jar at listing
+ * time, so a prune that only ever looked at the file once cannot destroy a
+ * concurrent resolve's freshly-written replacement at the same path.
+ *
+ * A missing, unreadable, or malformed sidecar answers with no identity to
+ * prove - {@link discardCachedDownload} already treats that as licence to
+ * evict unconditionally, the "cannot prove otherwise" rule this module's own
+ * sidecar-less entries already rely on elsewhere.
+ *
+ * Exported for direct testing, the same way {@link pathContainsVersion} is.
+ */
+export declare function readDownloadEntryIdentity(jarPath: string): Promise<{
+    url: string;
+    contentSha256: string;
+} | undefined>;
 export type CacheRegistryConfig = {
     cacheDir: string;
     sqlitePath: string;

package/dist/cache-registry.js

@@ -4,7 +4,7 @@ import { join, resolve } from "node:path";
 import { mapWithConcurrencyLimit } from "./concurrency.js";
 import { createError, ERROR_CODES } from "./errors.js";
 import { normalizeOptionalPathForHost } from "./path-converter.js";
-import { downloadSidecarPath, isDownloadSidecarPath } from "./repo-downloader.js";
+import { discardCachedDownload, downloadSidecarPath, isDownloadSidecarPath } from "./repo-downloader.js";
 import { openDatabase } from "./storage/db.js";
 import { getProcessWorkspaceContextCache } from "./workspace-context-cache.js";
 export const PUBLIC_CACHE_KINDS = [
@@ -528,6 +528,33 @@ async function downloadSidecarSizeBytes(downloadPath) {
         return 0;
     }
 }
+/**
+ * The identity `deleteEntries` captures for a downloads-cache jar at listing
+ * time, so a prune that only ever looked at the file once cannot destroy a
+ * concurrent resolve's freshly-written replacement at the same path.
+ *
+ * A missing, unreadable, or malformed sidecar answers with no identity to
+ * prove - {@link discardCachedDownload} already treats that as licence to
+ * evict unconditionally, the "cannot prove otherwise" rule this module's own
+ * sidecar-less entries already rely on elsewhere.
+ *
+ * Exported for direct testing, the same way {@link pathContainsVersion} is.
+ */
+export async function readDownloadEntryIdentity(jarPath) {
+    try {
+        const parsed = JSON.parse(await readFile(downloadSidecarPath(jarPath), "utf8"));
+        if (typeof parsed.url === "string" &&
+            typeof parsed.contentSha256 === "string" &&
+            parsed.contentSha256.length > 0) {
+            return { url: parsed.url, contentSha256: parsed.contentSha256 };
+        }
+    }
+    catch {
+        // Missing, unreadable, or malformed sidecar: nothing to identify these
+        // bytes with.
+    }
+    return undefined;
+}
 /**
  * Binary-remap cache entries are keyed by the final artifact id even when the
  * on-disk entry is a corrupt final directory or a leftover temp path.
@@ -682,7 +709,19 @@ export function createCacheRegistry(config) {
         async deleteEntries(input) {
             const entries = await collectEntries(input.cacheKinds, input.selector);
             const selectedBytes = entries.reduce((total, entry) => total + entry.sizeBytes, 0);
+            const warnings = [];
+            const failedEntries = [];
             if (input.executionMode === "apply") {
+                // Captured now, against the listing this call just made, rather than
+                // re-read right before each unlink below: the identity has to describe
+                // what THIS call selected, not whatever a concurrent resolve may have
+                // already replaced it with by the time the loop below reaches it.
+                const downloadIdentities = new Map();
+                for (const entry of entries) {
+                    if (entry.cacheKind === "downloads") {
+                        downloadIdentities.set(entry.path, await readDownloadEntryIdentity(entry.path));
+                    }
+                }
                 const db = openDb(config);
                 try {
                     for (const entry of entries) {
@@ -695,12 +734,40 @@ export function createCacheRegistry(config) {
                             continue;
                         }
                         if (entry.cacheKind === "downloads") {
-                            // The sidecar is part of this entry, so it goes with the jar —
-                            // outside the existsSync guard below, so a jar that vanished
-                            // out-of-band since the listing still takes its sidecar with it
-                            // instead of leaving an orphan behind. `force` makes a missing
-                            // sidecar a no-op.
-                            await rm(downloadSidecarPath(entry.path), { force: true });
+                            // Route through the same sidecar-identity check every other
+                            // eviction of this shared cache goes through, instead of an
+                            // unconditional unlink that cannot tell a poisoned jar from a
+                            // concurrent resolve's good one sitting at the same path. This
+                            // also retires the sidecar, so it goes with the jar exactly as
+                            // before - but only when the check above says the jar is still
+                            // the one this call listed. See discardCachedDownload's doc
+                            // comment in repo-downloader.ts for what the check does and does
+                            // not close.
+                            const expectedIdentity = downloadIdentities.get(entry.path);
+                            discardCachedDownload(entry.path, expectedIdentity);
+                            // discardCachedDownload swallows a genuine unlink failure
+                            // (EACCES, EBUSY, a locked file, ...) - documented there as an
+                            // accepted limitation for its own best-effort callers. That is
+                            // wrong for this explicit, user-facing delete/prune request:
+                            // verify the postcondition instead of trusting the call's
+                            // silence. The jar surviving is only a LEGITIMATE decline when
+                            // the identity recorded beside it now genuinely differs from
+                            // what this call captured at listing time - i.e. a concurrent
+                            // resolve's replacement is sitting there, exactly the case
+                            // discardCachedDownload itself declines for. A jar that is
+                            // still present with no such change (or no readable identity at
+                            // all) means the removal itself failed.
+                            if (existsSync(entry.path)) {
+                                const currentIdentity = await readDownloadEntryIdentity(entry.path);
+                                const declinedForConcurrentReplacement = expectedIdentity !== undefined &&
+                                    currentIdentity !== undefined &&
+                                    currentIdentity.contentSha256 !== expectedIdentity.contentSha256;
+                                if (!declinedForConcurrentReplacement) {
+                                    warnings.push(`Could not delete cached download (it may be locked or read-only): ${entry.path}`);
+                                    failedEntries.push(entry);
+                                }
+                            }
+                            continue;
                         }
                         if (existsSync(entry.path)) {
                             // Only binary-remap inventory can return directories as entries;
@@ -713,10 +780,11 @@ export function createCacheRegistry(config) {
                     db?.close();
                 }
             }
+            const failedBytes = failedEntries.reduce((total, entry) => total + entry.sizeBytes, 0);
             return {
-                deletedEntries: entries.length,
-                deletedBytes: selectedBytes,
-                warnings: []
+                deletedEntries: entries.length - failedEntries.length,
+                deletedBytes: selectedBytes - failedBytes,
+                warnings
             };
         },
         async pruneEntries(input) {

package/dist/entry-tools/analyze-mod-service.d.ts

@@ -40,9 +40,9 @@ export declare const analyzeModShape: {
         apply: "apply";
     }>>;
     detail: z.ZodOptional<z.ZodEnum<{
+        full: "full";
         summary: "summary";
         standard: "standard";
-        full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
         [x: string]: string;
@@ -88,9 +88,9 @@ export declare const analyzeModSchema: z.ZodObject<{
         apply: "apply";
     }>>;
     detail: z.ZodOptional<z.ZodEnum<{
+        full: "full";
         summary: "summary";
         standard: "standard";
-        full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
         [x: string]: string;

package/dist/entry-tools/analyze-symbol-service.d.ts

@@ -62,9 +62,9 @@ export declare const analyzeSymbolShape: {
     maxRows: z.ZodOptional<z.ZodNumber>;
     maxCandidates: z.ZodDefault<z.ZodNumber>;
     detail: z.ZodOptional<z.ZodEnum<{
+        full: "full";
         summary: "summary";
         standard: "standard";
-        full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
         [x: string]: string;
@@ -132,9 +132,9 @@ export declare const analyzeSymbolSchema: z.ZodObject<{
     maxRows: z.ZodOptional<z.ZodNumber>;
     maxCandidates: z.ZodDefault<z.ZodNumber>;
     detail: z.ZodOptional<z.ZodEnum<{
+        full: "full";
         summary: "summary";
         standard: "standard";
-        full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
         [x: string]: string;

package/dist/entry-tools/batch-class-members-service.d.ts

@@ -1,6 +1,7 @@
 import { type ResponseDetailLevel } from "../response-utils.js";
 import type { GetClassMembersInput, GetClassMembersOutput, ResolveArtifactInput, ResolveArtifactOutput } from "../source-service.js";
-import type { ArtifactScope, MappingSourcePriority, ResolveArtifactTargetInput, SourceMapping } from "../types.js";
+import type { ArtifactScope, MappingSourcePriority, SourceMapping } from "../types.js";
+import type { SourceLookupTargetInput } from "../tool-schemas.js";
 import type { MemberProjection } from "../source/class-source/members-builder.js";
 import { type BatchOutput } from "./batch-runner.js";
 export type BatchClassMembersDeps = {
@@ -16,7 +17,7 @@ export type BatchClassMembersEntry = {
     maxMembers?: number;
 };
 export type BatchClassMembersInput = {
-    target: ResolveArtifactTargetInput;
+    target: SourceLookupTargetInput;
     mapping?: SourceMapping;
     sourcePriority?: MappingSourcePriority;
     allowDecompile?: boolean;

package/dist/entry-tools/batch-class-members-service.js

@@ -16,6 +16,16 @@ export class BatchClassMembersService {
             concurrency,
             failFast,
             resolveSharedArtifact: async () => {
+                // target.kind === "artifact" reuses an already-resolved artifactId,
+                // short-circuiting resolution exactly as get-class-members's own
+                // `kind:"artifact"` target does (src/index.ts normalizeSourceLookupTarget).
+                // No provenance is invented for a reused artifact: an unknown id is left
+                // to surface per-entry (the same SOURCE_NOT_FOUND getClassMembers raises
+                // for an unknown artifactId), since resolveSharedArtifact has no way to
+                // validate existence without calling deps.resolveArtifact.
+                if (input.target.kind === "artifact") {
+                    return { artifactId: input.target.artifactId };
+                }
                 const resolved = await this.deps.resolveArtifact({
                     target: input.target,
                     mapping: input.mapping,
@@ -49,12 +59,16 @@ export class BatchClassMembersService {
                 const raw = (await this.deps.getClassMembers({
                     artifactId: sharedArtifact.artifactId,
                     // This artifactId is OURS, not the caller's: the shared target was
-                    // resolved above and every entry is dispatched by the result. Without
-                    // saying so, get-class-members reads the bare presence of an
-                    // artifactId as the caller having named the artifact, and reports a
-                    // missing binary jar as their mistake - once per entry - though
-                    // `target` here cannot name an artifact at all. Only a jar the caller
-                    // named themselves is genuinely their choice.
+                    // resolved (or, for target.kind==="artifact", reused) above and every
+                    // entry is dispatched by the result. Without saying so, get-class-members
+                    // reads the bare presence of an artifactId as the caller having named
+                    // the artifact, and reports a missing binary jar as their mistake - once
+                    // per entry. A `kind:"artifact"` target is a resolved-id handle, not a
+                    // caller choice either (mirrors resolveClassArtifactReference's
+                    // artifactSelectedByFor in inspect-minecraft/handlers/class-members.ts):
+                    // it says nothing about whether the artifact carries a binary jar and
+                    // cannot be re-resolved into one that does. Only a jar the caller named
+                    // themselves is genuinely their choice.
                     artifactSelectedBy: input.target.kind === "jar" ? "caller" : "tool",
                     className: entry.className,
                     access: entry.access,

package/dist/entry-tools/batch-class-source-service.d.ts

@@ -1,6 +1,7 @@
 import { type ResponseDetailLevel } from "../response-utils.js";
 import type { GetClassSourceInput, GetClassSourceOutput, ResolveArtifactInput, ResolveArtifactOutput } from "../source-service.js";
-import type { ArtifactScope, MappingSourcePriority, ResolveArtifactTargetInput, SourceMapping } from "../types.js";
+import type { ArtifactScope, MappingSourcePriority, SourceMapping } from "../types.js";
+import type { SourceLookupTargetInput } from "../tool-schemas.js";
 import { type BatchOutput } from "./batch-runner.js";
 type SourceMode = "metadata" | "snippet" | "full";
 export type BatchClassSourceEntry = {
@@ -13,7 +14,7 @@ export type BatchClassSourceEntry = {
     outputFile?: string;
 };
 export type BatchClassSourceInput = {
-    target: ResolveArtifactTargetInput;
+    target: SourceLookupTargetInput;
     mapping?: SourceMapping;
     sourcePriority?: MappingSourcePriority;
     allowDecompile?: boolean;

package/dist/entry-tools/batch-class-source-service.js

@@ -16,6 +16,16 @@ export class BatchClassSourceService {
             concurrency,
             failFast,
             resolveSharedArtifact: async () => {
+                // target.kind === "artifact" reuses an already-resolved artifactId,
+                // short-circuiting resolution exactly as get-class-source's own
+                // `kind:"artifact"` target does (src/index.ts normalizeSourceLookupTarget).
+                // No provenance is invented for a reused artifact: an unknown id is left
+                // to surface per-entry (the same SOURCE_NOT_FOUND getClassSource raises
+                // for an unknown artifactId), since resolveSharedArtifact has no way to
+                // validate existence without calling deps.resolveArtifact.
+                if (input.target.kind === "artifact") {
+                    return { artifactId: input.target.artifactId };
+                }
                 const resolved = await this.deps.resolveArtifact({
                     target: input.target,
                     mapping: input.mapping,

package/dist/entry-tools/compare-minecraft-service.d.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import type { DiffClassSignaturesOutput } from "../source-service.js";
-import type { CompareVersionsOutput } from "../version-diff-service.js";
+import { type CompareVersionsOutput } from "../version-diff-service.js";
 import type { GetRegistryDataOutput } from "../registry-service.js";
 export declare const compareMinecraftShape: {
     task: z.ZodOptional<z.ZodEnum<{
@@ -38,9 +38,9 @@ export declare const compareMinecraftShape: {
         registry: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>], "kind">;
     detail: z.ZodOptional<z.ZodEnum<{
+        full: "full";
         summary: "summary";
         standard: "standard";
-        full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
         [x: string]: string;
@@ -86,9 +86,9 @@ export declare const compareMinecraftSchema: z.ZodObject<{
         registry: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>], "kind">;
     detail: z.ZodOptional<z.ZodEnum<{
+        full: "full";
         summary: "summary";
         standard: "standard";
-        full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
         [x: string]: string;
@@ -122,10 +122,33 @@ type CompareMinecraftDeps = {
         includeData?: boolean;
         maxEntriesPerRegistry?: number;
     }) => Promise<GetRegistryDataOutput>;
+    /**
+     * Raw `libraries[].name` coordinates for one version, used only by
+     * migration-overview to surface library swaps (e.g. LWJGL GLFW replaced by
+     * SDL) that a class/registry diff cannot see. Optional so existing callers
+     * that do not wire it keep working: migration-overview simply omits the
+     * libraries block when this is absent.
+     */
+    getVersionLibraries?: (input: {
+        version: string;
+    }) => Promise<string[]>;
+};
+export type CompareMinecraftOptions = {
+    /**
+     * Deadline in milliseconds for fetching both sides' library lists during
+     * migration-overview, so a restart with cached jars but no network access
+     * fails fast instead of waiting the full underlying fetch timeout. On
+     * expiry the libraries block is omitted and a warning is added; the
+     * in-flight fetch is left to continue in the background (it may still
+     * warm the version-detail cache). Test-only injection point — never read
+     * from an environment variable.
+     */
+    libraryDiffDeadlineMs?: number;
 };
 export declare class CompareMinecraftService {
     private readonly deps;
-    constructor(deps: CompareMinecraftDeps);
+    private readonly libraryDiffDeadlineMs;
+    constructor(deps: CompareMinecraftDeps, options?: CompareMinecraftOptions);
     execute(input: CompareMinecraftInput): Promise<Record<string, unknown> & {
         warnings?: string[];
     }>;

package/dist/entry-tools/compare-minecraft-service.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { diffLibraries } from "../version-diff-service.js";
 import { createError, ERROR_CODES } from "../errors.js";
 import { buildIncludeSchema, detailSchema, positiveIntSchema } from "./entry-tool-schema.js";
 import { buildEntryToolMeta, buildEntryToolResult, createNextAction, createSummarySubject, createTruncationMeta } from "./response-contract.js";
@@ -42,10 +43,37 @@ export const compareMinecraftSchema = z.object(compareMinecraftShape);
 function compareStatusFromCounts(changedCount) {
     return changedCount > 0 ? "changed" : "unchanged";
 }
+/** Default bound on migration-overview's library enrichment (see `libraryDiffDeadlineMs`). */
+const DEFAULT_LIBRARY_DIFF_DEADLINE_MS = 5000;
+class LibraryDiffTimeoutError extends Error {
+}
+/**
+ * Races `promise` against a `ms` timer. The timer is always cleared (on
+ * either settlement) and unref'd so it can never keep the process alive.
+ */
+function withDeadline(promise, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new LibraryDiffTimeoutError(`timed out after ${ms}ms`));
+        }, ms);
+        if (typeof timer.unref === "function") {
+            timer.unref();
+        }
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
 export class CompareMinecraftService {
     deps;
-    constructor(deps) {
+    libraryDiffDeadlineMs;
+    constructor(deps, options) {
         this.deps = deps;
+        this.libraryDiffDeadlineMs = options?.libraryDiffDeadlineMs ?? DEFAULT_LIBRARY_DIFF_DEADLINE_MS;
     }
     async execute(input) {
         const task = input.task && input.task !== "auto"
@@ -362,6 +390,32 @@ export class CompareMinecraftService {
                 const registrySignals = compare.registry?.summary.registriesChanged ?? 0;
                 const status = compareStatusFromCounts(classSignals + registrySignals);
                 const representativeClassName = compare.classes?.added[0] ?? compare.classes?.removed[0];
+                // Library changes (e.g. LWJGL GLFW replaced by SDL) never show up in the
+                // class/registry diff above, so fetch and diff them separately. This must
+                // never fail the whole migration-overview: a missing dependency wiring, a
+                // fetch failure, or a deadline expiry (e.g. offline after a restart, with
+                // only cached jars) just omits the block and adds a warning. On a
+                // timeout, the in-flight fetch is left running — it may still warm the
+                // version-detail cache for a later call — we simply stop waiting on it.
+                let librariesResult;
+                const libraryWarnings = [];
+                if (this.deps.getVersionLibraries) {
+                    try {
+                        const [fromLibraries, toLibraries] = await withDeadline(Promise.all([
+                            this.deps.getVersionLibraries({ version: subject.fromVersion }),
+                            this.deps.getVersionLibraries({ version: subject.toVersion })
+                        ]), this.libraryDiffDeadlineMs);
+                        librariesResult = diffLibraries(fromLibraries, toLibraries);
+                    }
+                    catch (error) {
+                        if (error instanceof LibraryDiffTimeoutError) {
+                            libraryWarnings.push(`Library comparison between ${subject.fromVersion} and ${subject.toVersion} timed out after ${this.libraryDiffDeadlineMs}ms.`);
+                        }
+                        else {
+                            libraryWarnings.push(`Could not compare libraries between ${subject.fromVersion} and ${subject.toVersion}: ${error instanceof Error ? error.message : String(error)}`);
+                        }
+                    }
+                }
                 const nextActions = representativeClassName
                     ? [
                         createNextAction("compare-minecraft", {
@@ -399,7 +453,13 @@ export class CompareMinecraftService {
                             }),
                             counts: {
                                 classSignals,
-                                registrySignals
+                                registrySignals,
+                                ...(librariesResult
+                                    ? {
+                                        librariesAdded: librariesResult.addedCount,
+                                        librariesRemoved: librariesResult.removedCount
+                                    }
+                                    : {})
                             },
                             nextActions
                         },
@@ -413,11 +473,12 @@ export class CompareMinecraftService {
                                         : registrySignals > 0
                                             ? "registry"
                                             : "minimal",
-                                nextActions
+                                nextActions,
+                                ...(librariesResult ? { libraries: librariesResult } : {})
                             }
                         }
                     }),
-                    warnings: compare.warnings
+                    warnings: [...compare.warnings, ...libraryWarnings]
                 };
             }
             default:

package/dist/entry-tools/entry-tool-schema.d.ts

@@ -1,8 +1,8 @@
 import { z } from "zod";
 export declare const detailSchema: z.ZodEnum<{
+    full: "full";
     summary: "summary";
     standard: "standard";
-    full: "full";
 }>;
 export declare const includeGroupSchema: z.ZodEnum<{
     workspace: "workspace";
@@ -17,6 +17,7 @@ export declare const includeGroupSchema: z.ZodEnum<{
     samples: "samples";
     timings: "timings";
     matrix: "matrix";
+    artifact: "artifact";
     provenance: "provenance";
     descriptors: "descriptors";
     diff: "diff";
@@ -27,7 +28,6 @@ export declare const includeGroupSchema: z.ZodEnum<{
     paths: "paths";
     owners: "owners";
     cacheEntries: "cacheEntries";
-    artifact: "artifact";
     classes: "classes";
 }>;
 export declare const executionModeSchema: z.ZodEnum<{

package/dist/entry-tools/inspect-minecraft-service.d.ts

@@ -251,9 +251,9 @@ export declare const inspectMinecraftShape: {
     }, z.core.$strip>], "kind">>;
     includeSnapshots: z.ZodDefault<z.ZodBoolean>;
     detail: z.ZodOptional<z.ZodEnum<{
+        full: "full";
         summary: "summary";
         standard: "standard";
-        full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
         [x: string]: string;
@@ -512,9 +512,9 @@ export declare const inspectMinecraftSchema: z.ZodObject<{
     }, z.core.$strip>], "kind">>;
     includeSnapshots: z.ZodDefault<z.ZodBoolean>;
     detail: z.ZodOptional<z.ZodEnum<{
+        full: "full";
         summary: "summary";
         standard: "standard";
-        full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
         [x: string]: string;

package/dist/entry-tools/manage-cache-service.d.ts

@@ -40,9 +40,9 @@ export declare const manageCacheShape: {
         projectPath: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     detail: z.ZodOptional<z.ZodEnum<{
+        full: "full";
         summary: "summary";
         standard: "standard";
-        full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
         [x: string]: string;
@@ -94,9 +94,9 @@ export declare const manageCacheSchema: z.ZodObject<{
         projectPath: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     detail: z.ZodOptional<z.ZodEnum<{
+        full: "full";
         summary: "summary";
         standard: "standard";
-        full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
         [x: string]: string;