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

package/CHANGELOG.md

@@ -7,6 +7,94 @@ and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2
 
 ## [Unreleased]
 
+## [7.0.0-rc.3] - 2026-09-07
+
+### Changed
+
+- **A jar named by path, a Minecraft version, or a workspace now takes its `artifactId` from a sha256 of the identified jar's bytes**, not from the jar's path plus its modification time and size. 7.0.0-rc.1 and 7.0.0-rc.2 moved the Maven-coordinate routes onto content hashing; this release moves the rest. `target.kind="version"` and `target.kind="workspace"` resolve through the same jar route, so the rule covers Minecraft's own runtime jar as well as a jar you name, and the lightweight artifact probe behind `validate-project task="project-summary"` follows it too. A `touch`, a cache eviction followed by a re-fetch of byte-identical bytes, or a restore from backup therefore no longer mints a new id or forces a re-decompile. Three bounds. The jar's symlink-resolved path is still part of the id, so two byte-identical jars at two different real paths remain two artifacts. Within one server process a file's digest is reused while its size, modification time, inode and inode-change time all still match, so on a filesystem that does not advance the inode-change time on a write, an in-place replacement of the same length whose modification time was restored can be served the earlier digest until that memo entry is evicted. And one pre-existing limit is untouched: when a Loom split-source pair is indexed together, the artifact's signature comes from the primary sources jar only, so a change confined to the companion jar is not represented in the id.
+- **Upgrade cost of the identity change above.** Every artifact reached through `target.kind="jar"`, `"version"` or `"workspace"` — the Minecraft runtime included — gets a new `artifactId` on its first resolve after upgrading and re-indexes there, with a fresh decompile wherever the decompile branch is reached. There is deliberately no migration shim. An `artifactId` you already hold keeps resolving out of the index and does not re-index. The decompiled and remapped outputs stored under the previous ids are not reachable from the new ones, and nothing reclaims them as part of the upgrade; they stay visible to `manage-cache` under the `decompiled-source` and `binary-remap` cache kinds. Nothing bounds that first call end to end — see the upgrade note under Documentation — so on a large jar it can surface as a client-side request timeout rather than as a slow success.
+- **Wire contract change.** The `artifactSignature` field returned by the `mc://artifact/{artifactId}` resource is now a bare 64-character sha256 hex digest, or that digest followed by `:decompile`. For an artifact reached through a jar, version or workspace target it was previously `<mtimeMs>:<size>`, so a client matching that shape — anything keyed to a digits-colon-digits pattern — stops matching. The new shape applies to artifacts resolved after upgrading; an artifact recorded before the upgrade and reached by an `artifactId` you still hold returns the signature it was stored with, so a client that keeps old ids must accept both shapes. Artifacts reached through a Maven coordinate already published a bare digest and are unchanged. This is the only place the field reaches a client: no tool response carries it, and `resolve-artifact` and `manage-cache` never did.
+- **Behaviour change — two stdio header shapes that used to frame now end the session.** A `Content-Length` header block followed by an extra empty line is malformed, because the declared length does not count that line. Previously two of the four such shapes — an LF-terminated header line closed by a CRLF empty line, followed by either another CRLF or another LF — happened to skip past the extra line and framed correctly. All four now read alike: the body window opens one or two bytes early, by the length of the extra line's own terminator, so the JSON does not parse, and a body-parse failure is framing-fatal, so the session ends and the frames behind it are lost. The other two shapes already failed this way. One case still slips through in either direction: the window is shifted rather than mis-sized, so a declared length that happens to count enough trailing whitespace absorbs the shift and the frame is delivered normally.
+
+### Fixed
+
+- Cancelling a queued request that reuses a running `validate-project`'s JSON-RPC id no longer lets other requests run on the worker alongside that `validate-project`. A `notifications/cancelled` for such an id matched the queued entry and, on the id match alone, released the dispatch barrier the running `validate-project` was holding, so other work was admitted beside it. Cancellation now releases the barrier only for a queued request that raised it itself; 7.0.0-rc.2's rule that a request cannot release a barrier it does not hold now covers cancellation too. Nothing could be stranded by this: the barrier was wrongly released, never wrongly left standing.
+- Two identity bugs on symlinked paths are fixed. The artifact probe behind `validate-project task="project-summary"` and `resolve-artifact` now agree on the `artifactId` of a runtime jar reached through a symlinked directory. The probe composed its id from the path as handed to it while `resolve-artifact` resolved the symlink first, so `tasks["minecraft.artifact.resolved"].artifactId` and `resolve-artifact` reported two different ids for one jar; both now resolve the path first, and the probe's id changes for such jars. Separately, when a jar named by path carries no Java sources and its `<basename>-sources.jar` sibling supplies them, and that sibling is itself a symlink, its id now follows the real path. The `sourceJarPath` the response publishes is unchanged.
+- A stdio peer that ends its `Content-Length` header lines with a bare LF but closes the block with a CRLF empty line can now be read at all. That shape matched neither of the two terminator patterns the reader looked for, so the block was never recognized: the reader accumulated until it hit the 8 KiB header ceiling and then ended the session, losing that request and every request behind it. A header block now ends at its first empty line whichever way the lines are terminated, so all four combinations frame, and a `\r\n\r\n` sequence inside a JSON body — legal whitespace — can no longer be mistaken for the terminator. This removes that stall, not the framing-fatal class as a whole: two header shapes that used to frame by accident now fail, which is the behaviour change recorded under Changed.
+- Several ways a request could end up with no reply, or with two, are closed in the stdio supervisor. A request rejected because the queue was full now lowers the `validate-project` dispatch barrier it had raised, instead of leaving it standing with nothing able to lower it and nothing behind it able to dispatch. A fault while handling a worker's response, a fault inside the admission recovery itself, and a dispatch that fails while the queue drains are each now answered with a JSON-RPC `-32603` on the request's own id — previously the first two escaped into the frame reader, which reported a parse error and dropped the frame, and the third stranded the request and parked everything behind it; because only `validate-project` arms a deadline, any other request lost that way waited on its id for the life of the session. A missing pending entry is no longer read as proof the client was answered: when a fault interrupts the supervisor between dropping its own record of the request and handing the reply to the client, the id is still answered; a plain failed write of a reply is still only logged. A rollback that itself fails no longer lets a second terminal reply go out for one id. An in-flight `initialize` whose answer is lost to a fault now restarts the handshake against a replacement worker, where before it could wait indefinitely. And an error object whose own `toString` throws can no longer slip past these guards.
+- Two limits on the repairs above, stated because a user can reach them. When the supervisor's cleanup after such a fault cannot prove the request was removed, it reports and stands down rather than risk two replies for one id; only `validate-project` carries a deadline of its own, so any other request left in that state waits for the worker to exit. And the record that discards a worker's late answer for an already-settled id holds at most 1024 ids at a time — a pre-existing cap this release does not change — so beyond that the oldest is evicted and a very old worker's late answer for an evicted id would pass through.
+
+### Performance
+
+- A repository's definitive rejection of a URL — 403, 404 or 410 — is now remembered, so resolving the same target again does not re-issue the requests every configured repository already refused. Previously nothing about a failed download was recorded: only bytes land in the download cache, so a coordinate whose sources jar does not exist paid the full repository sweep on every resolve, and a caller retrying after a timeout paid the identical sweep again. The bounds are part of the feature. The records live in memory only and are lost on restart. Each expires after about five minutes. At most 1024 records are kept at once; past that, expired records are dropped first and then the oldest, so a record can be lost before its five minutes are up. Only those three statuses are eligible: a 5xx, a 429, a 401, a request timeout and a network error are never remembered and are always retried. A `-SNAPSHOT` coordinate is never recorded — it is the one version shape this server treats as mutable — since its absence can be a publish in progress. And the records are kept per cache directory, so two configurations pointing at different cache directories never inherit each other's verdicts.
+
+### Documentation
+
+- **Correction to `docs/tool-reference.md` as shipped in 7.0.0-rc.2.** That release corrected the "Inspecting a Fabric / loader dependency like vanilla" target-shape table's claim that dependency members always come back with `qualityFlags: ["dependency-mapping-unverified"]`, but left the identical claim standing in the prose above it. The prose now names both branches: for a non-obfuscated mapping request, a source-backed jar that can honor it returns `mappingApplied` equal to the request and `qualityFlags` including `"source-backed"`; every other dependency jar answering that same request returns `mappingApplied: "obfuscated"` and `qualityFlags` including `"dependency-mapping-unverified"`, with names taken verbatim from the jar's compiled names. A request that asks for `"obfuscated"` outright never reaches that branch: it passes through as `mappingApplied: "obfuscated"` with `"source-backed"` or `"decompiled"`, never with `"dependency-mapping-unverified"`.
+- `docs/tool-reference.md`'s "which requests count as tool-chosen" list in the error-classification section named `get-class-members`, `batch-class-members`, and `inspect-minecraft`'s `class-members` task but omitted `verify-mixin-target`, which reads its target's members from bytecode under the same rule and carries the same per-site `issueOrigin` override. The list now names all four.
+- **Correction to `docs/tool-reference.md` as shipped in 7.0.0-rc.2.** The environment-variable section documented byte-derived jar identity only for jars downloaded through `MCP_SOURCE_REPOS`. It now also records that jars served from `MCP_LOCAL_M2` and the Gradle dependency cache are identified from their bytes the same way whenever reached through a Maven coordinate. The section now also documents the byte-derived rule for jar-path, version and workspace targets, which this release introduces (see Changed).
+- **Correction to `docs/tool-reference.md` as shipped in 7.0.0-rc.2.** The legacy-era exceptions bullet claimed the advertised `inputSchema` bytes are "identical to the pre-migration snapshots" without qualification. The wording now says what the guarantee covers: the bytes `tools/list` advertises for legacy-era tools come from frozen pre-migration contracts, and those contracts are deliberately extended when a tool gains a parameter in a later release — as `projectPath` was added to four tools in 7.0.0-rc.2 itself. The parity guarantee was never broken; only its description was imprecise about what it promises.
+- **The 7.0.0-rc.2 section was corrected in place.** New practice: a false statement in a released section is now amended where readers find it, not merely annotated from a later section. Two claims in its Maven-coordinate hardening entry were wrong. First, "naming the offending segment in `details.component`, including when a mandatory segment is blank": no `details` object reaches a client, and the message names the segment only for a character-rule rejection — a blank segment or a wrong-shaped coordinate names none — so it now reads "whose message names the offending segment when a segment breaks the character rule"; its `dependency`-route `fieldErrors` half is untouched. Second, "no write location was ever reachable, since every cache and artifact write derives its filename from a sha256": that reason is false server-wide — the mapping caches name files from a version string — so only the reason changed, to "because nothing on these routes writes to a coordinate-derived path"; the conclusion stands — those version-derived paths are written only after a successful fetch from a fixed upstream, which a traversal-bearing version cannot reach. Both sentences carry a trailing `(Corrected 2026-09-05; see [Unreleased].)`; the record they point to was written under `[Unreleased]` and now lives in this entry. The published 7.0.0-rc.2 npm tarball ships the changelog as it was released and cannot be amended, so a reader of the copy installed from npm still sees the original wording.
+- **The 7.0.0-rc.0 section was corrected in place.** Its "Ending the session no longer leaves a worker process behind" entry said the signal path and the supervisor-fault path both "exit non-zero once the worker group is collected or a bounded watchdog expires". That is false for the signal path: `SIGHUP` runs the ordinary cooperative shutdown and the process exits with code 0 once the detached worker group is collected, exactly as when stdin closes; the non-zero code belongs to the uncaught-supervisor-fault path, which is how a launcher tells a crash from a clean stop. That entry now states the two exit codes separately and carries a trailing `(Corrected 2026-09-05; see [Unreleased].)`. Correcting it also falsified the closing clause of 7.0.0-rc.2's "Correction to 7.0.0-rc.0." note — "the published 7.0.0-rc.0 entry is left as it stands" — so that clause now records the rc.0 entry as corrected in place and carries the same marker. The published 7.0.0-rc.0 and 7.0.0-rc.2 npm tarballs ship their changelogs as released and cannot be amended, so a reader of either installed copy still sees the original wording.
+- **Upgrade note for 7.0.0-rc.2.** That release said each already-cached local dependency re-indexes once on its first resolve after upgrading, but only as a cost. It can be slow enough to matter: a consumer measured a 95.5-second first `get-class-members` call. Nothing bounds that first call end to end: individual stages carry their own budgets, but no deadline covers the call as a whole, and only `validate-project` has one. Stage progress is emitted by `validate-project` and `validate-mixin` alone, as the custom `$/stageUpdate` notification rather than `notifications/progress`, so it cannot reset a client's timeout even where it is emitted. Whether it returns or is cut off rests on the client's own request timeout, which this server neither sets nor observes. What a retry saves: the artifact index is SQLite and survives the timeout and a restart, so a retry addressed at the `artifactId` skips the re-index. A retry addressed at the same `target` skips the re-index too, and now also skips the repository sweep, but only within the bounds of the remembered rejections under Performance — in-process, about five minutes, definitive rejections only — and the sweep is paid again after a restart or once that window closes. The jar-identity change in this release adds one re-index, and where the decompile branch is reached a fresh decompile, to that same unbounded first call — for the Minecraft runtime as well as local dependencies. The 95.5-second measurement itself is unexplained.
+- `docs/tool-reference.md` now describes artifact identity as it works. Its environment-variable section states the byte-derived rule for jar-path, version and workspace targets alongside the coordinate routes, names which file each jar-route branch hashes, and records both bounds: the symlink-resolved path is still part of the id, and a file's digest is memoized within a process against its size, modification time, inode and inode-change time. The `mc://artifact/{artifactId}` row states the shape of the `artifactSignature` it returns. The `validate-project` task table and `README.md` both record that the artifact probe reads the runtime jar's bytes to derive the `artifactId` it reports.
+- `docs/tool-reference.md` now documents the remembered definitive rejections in its repository section, with the bounds on them: the eligible statuses, the roughly five-minute expiry, the `-SNAPSHOT` exclusion, the per-cache-directory keying, and the fact that the records are lost on restart.
+- `docs/tool-reference.md`'s Framing section now says where a `Content-Length` header block ends, that all four terminator combinations delimit one, and what an extra empty line after the terminator costs — including that the resulting body-parse failure is framing-fatal, and that a declared length counting enough trailing whitespace can absorb the shift instead. Its synthetic-terminal-response section now names the supervisor's internal-fault `-32603` replies alongside the queue-overflow, worker-restart, timeout and startup-failure shapes, and records the one case in which the supervisor deliberately sends nothing at all.
+
+## [7.0.0-rc.2] - 2026-09-04
+
+### Added
+
+- Artifact downloads are now capped at 512 MiB per transfer, configurable with `MCP_MAX_DOWNLOAD_BYTES`. The ceiling is checked against the declared `Content-Length` before the body is read and again against the bytes actually received, so a chunked or mis-declared response is caught too. A breach fails with `ERR_LIMIT_EXCEEDED`, is not retried, and its partial file is removed on a best-effort basis; a cached copy is never served in its place. When every repository trips the cap, the final `ERR_REPO_FETCH_FAILED` says so: `hints` tells you to raise `MCP_MAX_DOWNLOAD_BYTES`, and `context.repoFailureCode` is `"ERR_LIMIT_EXCEEDED"`. Previously only a 15-second timeout bounded a transfer, so a fast link serving a very large body could fill the disk. The cap is per transfer and is unrelated to total cache size.
+- Nested-jar extraction is now capped at 64 MiB per inner jar, configurable with `MCP_MAX_NESTED_JAR_ENTRY_BYTES`. The ceiling is checked against the entry's declared uncompressed size before extraction and against the bytes actually streamed. A breach fails that one entry with `ERR_LIMIT_EXCEEDED`; the shell jar's other inner jars still resolve. Previously inner jars were read whole into memory with no size check, so a highly compressible entry could expand far beyond the archive carrying it.
+- The `nestedJars` error field is now bounded in bytes as well as entry count, and says when it has been shortened. Entries longer than 256 bytes are dropped individually, the list stops at 8 KiB in total, and `nestedJarsTruncated: true` accompanies a shortened list wherever one is emitted. Previously a truncated inventory was indistinguishable from a complete one.
+- `resolve-artifact` now reports the `binary-jar-no-classes` quality flag for a binary jar that opens cleanly but contains no `.class` entry. Such jars are legitimate — `net.fabricmc:yarn` and `intermediary` `v2` carry only `mappings/mappings.tiny`, and a resource-only Fabric mod carries only `fabric.mod.json` and assets — so the flag describes the artifact and never refuses it. It is set for `coordinate`, `jar` and `version` targets alike. Known limit: a class-free jar that is not a Jar-in-Jar shell still fails during indexing with `ERR_DECOMPILER_FAILED` before any response exists, so the flag does not reach a caller in exactly that case.
+
+### Changed
+
+- **Wire contract change.** `context.jarHash` is renamed to `context.jarSignature` on `get-class-members` and `batch-class-members`. The value never was a hash of the jar's bytes: it is a signature over the jar's resolved path, modification time and size, useful for spotting that a jar changed between two responses but not as a content identity or cache key. The value and its derivation are unchanged. Callers reading `context.jarHash` must read `context.jarSignature` instead.
+- **Wire contract change.** An artifact named only by an opaque handle no longer draws the blame for carrying no binary jar. `get-class-members`, `batch-class-members` and `inspect-minecraft`'s `class-members` task now apply one rule: a caller-named jar target (`target: { kind: "jar", ... }`) is the only shape that reports `issueOrigin: "code_issue"`; every other shape, an `artifactId` or `resolved-id` handle from an earlier resolve included, reports `"tool_issue"`. Previously `get-class-members` reported `"code_issue"` for `target: { kind: "artifact", artifactId }`, even though a handle tells its holder nothing about whether the artifact has a binary jar and `resolve-artifact` does not accept one. `retryClass` is unchanged and still `"input"` here. The error now points at `manage-cache action="inspect"` with `selector: { artifactId }` and `include: ["cacheEntries"]`, which reports the artifact's stored jar as `meta.binaryJarPath` inside `cacheEntries`. Clients that branch on `issueOrigin` should read it per response rather than assume a fixed value per error code.
+- **A dependency's `artifactId` is now derived from the jar's bytes when the jar is served from `~/.m2` or the Gradle dependency cache**, not from its modification time and size. This applies to the routes that reach a jar through a Maven coordinate, `target.kind="dependency"` and `target.kind="coordinate"`; a jar named directly by path (`target.kind="jar"`) is unchanged and still takes its identity from that path with the file's modification time and size. 7.0.0-rc.1's content-derived `artifactId` covered only the remote-download path, so on the local path a `touch`, a cache eviction and re-fetch of identical bytes, or a filesystem restore still minted a new `artifactId`. Each already-cached local dependency gets a new `artifactId` and re-indexes once on its first resolve after upgrading, including a fresh decompile for binary-only dependencies.
+
+### Fixed
+
+- `search-class-source`, `get-artifact-file`, `list-artifact-files` and `index-artifact` now accept a top-level `projectPath` parameter, matching `find-class`, and advertise it in their `tools/list` `inputSchema`. Previously a `target.kind="workspace"` or unversioned `target.kind="dependency"` call to these four tools was rejected with an error asking for `projectPath`, but their schemas had no such field, so the error's own advice could not be followed.
+- A dependency resolve no longer warns that its requested mapping "is not enforced" when a source-backed jar actually supplied it. The warning used to fire whenever a non-obfuscated mapping was requested for a dependency, contradicting the same response's `mappingApplied` and `qualityFlags` when the mapping had genuinely succeeded. It now fires only when the binary remap was actually skipped, that is, when `qualityFlags` includes `dependency-mapping-unverified`.
+- A dependency's own coordinate version is no longer read as a signal about Minecraft's obfuscation state. A version that parses as a modern Minecraft version — any `26.x` or later, as `org.jetbrains:annotations:26.0.2` does — made a `mapping: "mojang"` request on a binary-only dependency return `mappingApplied: "mojang"` with no quality flag and no warning, claiming a remap that was never performed. Such a dependency now reports `mappingApplied: "obfuscated"` with the `dependency-mapping-unverified` flag and warning, on `resolve-artifact`, `get-class-source` and `get-class-members` alike. The obfuscation check now applies only to targets that genuinely name a Minecraft version — a `target.kind="version"`, or a `coordinate` target naming the Minecraft runtime itself such as `net.minecraft:client:26.1`; a `target.kind="dependency"` request is never treated as one — so vanilla resolution is unaffected.
+- `get-class-members` and `batch-class-members` now report `context.minecraftVersion: "unknown"` for a dependency artifact instead of a plausible-but-wrong value. The version used to be guessed from the jar's path, which for a jar served out of the Gradle cache yielded the cache-layout constant `2.1` and under `~/.m2` the dependency's own release number, and a fallback then substituted the dependency's coordinate version. The workspace's Minecraft version is not substituted either: `"unknown"` reports what the tool genuinely knows. Vanilla artifacts are unaffected.
+- `get-class-members`, `batch-class-members`, `find-class` and `get-class-source` now recognize a dependency artifact however it was reached. Previously only a `target.kind="dependency"` request marked the artifact as a dependency; the same jar reached by its Maven coordinate or reused by its `artifactId` was treated as vanilla, so `context.minecraftVersion` again reported the Gradle cache-layout constant `2.1` or the dependency's own release number, and a class-not-found miss drew a false hint to retry with `mapping="mojang"`. A dependency named by a Maven coordinate is now detected on every route, and `net.minecraft` alone no longer marks an artifact as Minecraft: the artifact name is read too, so `net.minecraft:launchwrapper:1.12` is a dependency, as is a group that merely ends in `net.minecraft` or an artifact whose name merely contains `minecraft-client`. A jar named by bare path (`target.kind="jar"`) under the Gradle dependency cache or the local Maven repository, wherever `MCP_LOCAL_M2` puts it, reports `"unknown"` unless the part of the path below the store's root names the Minecraft runtime; directories above the store are never consulted. Minecraft's own jars are unaffected. Remaining limit: a third-party jar whose own file name starts with `minecraft-`, such as `minecraft-client-helper`, still reports its own release number when named by a bare jar path; reach it with a `dependency` or `coordinate` target instead.
+- `batch-class-members` and `inspect-minecraft`'s `class-members` task no longer blame the caller when the artifact they themselves resolved from the request's target carries no binary jar. Both collapse the request to a single artifact before reading members, and the failure was reported as `issueOrigin: "code_issue"` — once per entry on a batch — pointing at an input that could not have chosen otherwise. It is now `"tool_issue"`, matching `get-class-members`. A caller who named a jar themselves (`target: { kind: "jar", ... }`) still gets `"code_issue"`. This closes the gap 7.0.0-rc.1 recorded as outstanding for `batch-class-members`.
+- A binary jar that `resolve-artifact` reports is now also persisted when the resolve was served from the warm cache. Previously that path skipped the write, so a binary companion that appeared in `~/.m2` or the Gradle cache after the artifact was first recorded, or the mojang-remapped jar reconciled for a `binary-remap:obf->mojang` artifact, reached the `resolve-artifact` response but not the stored artifact, and `get-class-members` on the returned `artifactId` then failed with `ERR_CONTEXT_UNRESOLVED` saying the artifact has no binary jar. Affected artifacts repair themselves on their next resolve; no re-index or cache clear is needed. A resolve that reaches no jar never clears a previously stored one.
+- Cached artifact bytes that a concurrent resolve or cache prune deleted are now re-downloaded instead of failing the call with a raw `ENOENT`. Both a cache hit and a `304` revalidation treat vanished bytes as a cache miss and transfer again — unconditionally in the 304 case, carrying no validator from any source, caller-supplied `requestHeaders` included. A 304 revalidation no longer overwrites a fresher freshness record that a concurrent resolve left beside replaced `-SNAPSHOT` bytes: that record's digest, `etag` and `lastModified` are reported as they stand and no extra transfer is made. A cached entry that is present but unreadable — a permission error, a directory where a jar should be — is now reported instead of being treated as a miss, which had put that URL on the network on every call while hiding the actionable error. When that failed every repository, the final `ERR_REPO_FETCH_FAILED` names the offending cache path and its errno (`EACCES`, `EISDIR`, `EPERM`, `EIO`) in `hints` and says to remove or repair it.
+- Evicting a poisoned download no longer destroys a concurrent resolve's good jar, and an eviction that cannot delete no longer leaves an entry the cache re-adopts forever. A response that is not a readable archive is dropped from the download cache, but the deletion named only the path, so when another resolve of the same URL had meanwhile finished a real jar into the same slot, that jar was deleted on the strength of a check run against different bytes. The eviction now compares the digest of the body it is rejecting with the identity record beside the file and leaves the file alone when they differ; this narrows the window rather than closing it, since another process can still replace the file between the comparison and the deletion. An entry no record can identify is still deleted, so a cache poisoned by an earlier version still heals itself. Separately, when the deletion itself fails — a read-only cache directory, say — the file is now truncated to zero bytes, which the cache treats exactly like a missing one, so the next transfer replaces it; previously whatever survived was served back and rejected again on every later resolve.
+- `Retry-After` is now honoured in the RFC 9110 HTTP-date form. That form used to parse as `NaN` and fall through to a roughly 200-millisecond backoff, hammering a server that had just asked for a long pause. The numeric form is now read strictly, so `Retry-After: 12abc` is malformed rather than 12 seconds. Both forms stay capped at 30 seconds, a date already in the past behaves like `Retry-After: 0`, and only the space and horizontal tab RFC 9110 permits are stripped: a value padded with a newline, a form feed or a non-breaking space stays malformed instead of being repaired into a pause. The delta is measured against the local clock rather than the response's `Date` header.
+- A caller-supplied Maven coordinate can no longer reach a jar outside the configured local repository. Every segment of `group:artifact:version[:classifier]` becomes a path component, and none was validated: an `artifactId` or `version` carrying `../` walked out of the repository root, and a `groupId` of `.`, `..` or `.a` landed at the filesystem root. Each segment is now trimmed and checked against one rule — 1 to 200 characters from `[A-Za-z0-9._+-]`, no leading `.`, no `..` — with `version` and `classifier` additionally admitting a space, because `net.fabricmc:yarn:1.14 Pre-Release 1+build.10:v2` is a real coordinate. A rejected coordinate fails with `ERR_COORDINATE_PARSE_FAILED`, whose message names the offending segment when a segment breaks the character rule; `g : a : 1.0` now resolves instead of failing on its padding. The `dependency` target route applies the same rule to `target.group` and `target.name` before it probes the Gradle cache (its old blocklist admitted `group="D:"` with `name="."`, which listed a directory outside the cache root into `candidatesSeen`), trims `target.version`, and names `target.group` or `target.name` in its field error instead of just `target`. Scope: the reachable impact was reading a file that is both named `<artifact>-<version>[-classifier][-sources].jar` and openable as a zip; no write location was ever reachable, because nothing on these routes writes to a coordinate-derived path. (Corrected 2026-09-05; see [Unreleased].)
+- One corrupt `-sources.jar` in `~/.m2` no longer aborts artifact resolution. A truncated or non-zip sources jar among the resolution candidates used to surface as a generic `ERR_ARTIFACT_RESOLUTION_FAILED`, with the Gradle cache, the remote sources repositories, the local-binary decompile branch and the remote binary fallbacks never tried. An unopenable candidate is now treated as "no sources here" and resolution moves on, as the binary side already did. A jar the caller named directly still reports the open failure rather than laundering it into "no sources".
+- A sources jar found in `~/.m2` or the Gradle module cache now picks its binary companion by opening the candidates, and looks in both stores. Previously each store took the first companion that merely existed, so a truncated or half-copied jar in one cache shadowed a good copy in the other, and the unusable path was what got recorded on the artifact, so every later `get-class-members` on that `artifactId` went to the broken file. Candidates are now tried in preference order, the sources jar's own store first, and the first one that opens wins. A companion that opens but holds no `.class` entry carries the `binary-jar-no-classes` quality flag here too.
+- `validate-access-widener` and `validate-access-transformer` no longer answer `ERR_CONTEXT_UNRESOLVED` because of a directory name above the Gradle cache. A runtime jar's loader was read from its whole path, so a Fabric workspace checked out under a folder called `forge`, `moddev-notes` or `srg-test` was taken for a Forge or NeoForge runtime and refused. The loader is now read only from the part of the path a build tool wrote — everything below the deepest dot-directory (`.gradle`, `.m2`), Gradle's `caches` root or a project `build` directory, or the file name alone when the path enters none of them. A NeoForge-patched jar inside a Loom cache is still reported as NeoForge.
+- A stdio peer that sends a `Content-Length` header and then stops sending the body no longer silences the connection. 7.0.0-rc.0 closed this only for a declared length above the frame limit; a smaller declared length followed by no body still parked the reader forever, with every later request stuck behind it. After 30 seconds with no further bytes the session now ends with a diagnostic naming the declared and received byte counts. The budget measures silence, not total transfer time: every arriving byte re-arms it, so a slow or very large body is never cut off.
+- A header block whose lines contradict each other — a second `Content-Length` line even when the first value was unusable, or a malformed line alongside a good one — is now rejected outright and ends the session. Previously the reader stopped at the first bad line and consumed only the header block, so the body bytes an earlier declaration had claimed were re-read as separate messages and the peer effectively chose where the frame ended. A block that never declares a usable length is still reported as an ordinary parse error and recovered from.
+- Peers that frame `Content-Length` headers with bare LF line endings are no longer mis-read when the JSON body contains a `\r\n\r\n` pair, which is legal JSON whitespace. A CRLF terminator anywhere in the buffer used to win over an earlier LF one, cutting the header block inside the body and losing that message and the next. The first terminator now wins, whichever style it is.
+- A fault while handling an already-decoded frame no longer changes how later replies are framed. Such a throw used to reset the detected framing mode, so every later response was silently downgraded to line framing while the faulting request went unanswered. The fault is now reported through the ordinary parse-error channel with the framing state left as it was, and it can no longer tear the session down.
+- A running `validate-project` no longer loses its timeout when a client reuses its JSON-RPC id. The deadline was matched by id alone, so a queued duplicate with the same id was timed out in its place while the real `validate-project` kept running with no deadline and still holding the dispatch barrier; whenever the worker never answered, everything queued behind it waited forever. A deadline now belongs to the exact request it was armed for, and a request that does not hold the barrier cannot release it.
+- An internal failure while handing a request to the MCP worker no longer leaves that request half-registered. The supervisor answers such a fault with a JSON-RPC `-32603` "failed to admit the request" error, but the entry it had already installed stayed live: for `validate-project` the abandoned deadline later fired a second reply for the same id, and the dispatch barrier stayed raised until it did. The `-32603` is now the only reply for that id — the entry, its deadline and any barrier it held are released before the error is written — and queued work resumes immediately. An `initialize` that faults at this point keeps its own handshake recovery and is not rolled back here.
+- A `tools/call` whose `arguments` are nested thousands of levels deep — a few KB on the wire — is now answered instead of vanishing. The argument redaction that runs at admission had no depth bound, so such a frame overflowed the stack and the request got no reply on an id the client then waited on forever. The walk now stops at 32 levels and reports anything deeper as `"<max-depth>"` in the diagnostic copies (`meta.timeout.redactedToolArgs`, `meta.restart.redactedToolArgs`, marked by `redactedToolArgsModified`); no real tool schema nests near that deep. Any request the supervisor cannot admit, for any reason, is now answered with JSON-RPC `-32603` rather than dropped.
+- A worker or JVM that writes one very long stderr line with no newline no longer makes the server's memory grow until that worker is next restarted. The pending line is capped at 64 KiB: the part already held is passed through as one truncated line with a `supervisor.worker_stderr_line_truncated` warning, the rest of that line is discarded, and normal line handling resumes at the next newline, so worker startup is still detected.
+- `compare-versions` no longer reports every class as both added and removed when only one of the two versions has usable Mojang mappings. Each side used to be lifted independently, so a pair where one side stayed obfuscated compared two different namespaces and returned `unchanged: 0` beside two full class lists. The diff now falls back to the jars' own class names on both sides, the `obfuscated` namespace the result already reported, and the warning announcing that fallback lists `version` alongside `packageFilter` in its `affectedFields`. One case the fallback cannot repair: when the two versions straddle Minecraft's move to unobfuscated names and the obfuscated side's mappings cannot be loaded, the jars' own names are still two different schemes, so `warnings` now says outright that the added and removed lists are not meaningful and `unchanged` will be near zero.
+- A mapping file that leaves a namespace column empty on a class row no longer files that class's fields and methods under the previous class. The previous name was left standing for that namespace, so every member row that followed was indexed under the wrong owner and a lookup could be answered with a member the owner does not declare. Such a row now clears the namespace instead.
+- `MCP_LOOM_TINY_MAX_INDEX_ENTRIES` now accepts only plain ASCII digits. A value such as `1e9`, `2_000_000`, `10M` or `1.9` used to be read from its leading digits as 1, 2, 10 or 1, small enough to truncate every real Loom mapping load; such a value now falls back to the heap-derived budget. A plain integer such as `250000` is still honoured, and may still be deliberately small.
+- `find-mapping` and `resolve-method-mapping-exact` now return the mapping loader's own warnings in `warnings` whenever a mapping was loaded, `mapping_unavailable` included, as `get-class-api-matrix` and `check-symbol-exists` already did. The notice that a Loom mapping index stopped at its entry budget — the one signal that the answer may be incomplete — was being dropped on exactly the two tools most likely to hit it, and a `mapping_unavailable` answer replaced those warnings with its own single "no mapping path is available" sentence; both now appear together. On a version with no Mojang mappings these two tools now also surface the pre-existing `does not expose client mappings URL` notice.
+- `resolve-method-mapping-exact` now says when a `not_found` was caused by an `owner` with no package. An unqualified owner cannot be projected into the target namespace and can never match, but the response explained the miss only as an inherited or relocated member. The message now names the owner and asks for the fully-qualified one.
+- A version-manifest or version-detail fetch that fails at the transport layer — DNS, a refused connection, a TLS handshake — now fails with `ERR_REPO_FETCH_FAILED` instead of `ERR_INTERNAL`, so a network fault no longer reads as a server bug. The underlying message travels in `details.cause`; the timeout mapping is unchanged.
+- `MCP_SQLITE_CACHE_KB` and `MCP_SQLITE_MMAP_SIZE` now also tune the artifact index that `manage-cache` opens. It used to open the same database on the built-in defaults — 8000 KiB page cache, 256 MiB memory map — whatever the two variables said.
+- A failure while rebuilding a corrupted artifact index now fails with `ERR_DB_FAILURE` and closes the half-opened database handle, instead of escaping as a raw filesystem error from a read-only directory or a full disk. `details.reason` is `"rebuild_failed"` and the underlying message is carried in the error message.
+
+### Documentation
+
+- `docs/tool-reference.md` no longer tells a caller to work around a parameter that now exists. Its "Essential Conventions" entry named `find-class` as the only flat-`artifactId` tool accepting a top-level `projectPath` and directed callers of the other four to resolve the artifact first, contradicting the "Common Pitfalls" entry in the same document. Both now state that all five tools accept a top-level `projectPath` for a target that cannot supply workspace context from its own fields; resolve-first stays documented in "Common Pitfalls" as the optional alternative it still is.
+- `docs/tool-reference.md` now documents the `context` block `get-class-members` and `batch-class-members` return. `jarSignature` is described as a signature over the jar's resolved path, modification time and size — good for spotting that the jar behind two responses is no longer the same file in the same state, usable neither as a content identity nor as a cache key. `minecraftVersion`, `mappingType`, `mappingNamespace` and `generatedAt` are described alongside it, including that `minecraftVersion` is `"unknown"` for a dependency artifact and for a jar inside a dependency store whose store-relative path does not name the Minecraft runtime, while a jar outside any such store is read from the first version-shaped token in its path.
+- **Correction to 7.0.0-rc.0.** That release's "Ending the session no longer leaves a worker process behind" entry says the signal path and the supervisor-fault path both "exit non-zero once the worker group is collected or a bounded watchdog expires". That is wrong about the signal path: `SIGHUP`, `SIGINT` and `SIGTERM` run the ordinary cooperative shutdown and the process exits with code 0 once the detached worker group is collected, exactly as when stdin closes. Only an uncaught supervisor fault (`supervisor.fatal`) and a client framing violation (`supervisor.client_framing_fatal`) set exit code 1 on a running session, which is what lets a launcher tell a crash from a clean stop. No code changed, and the 7.0.0-rc.0 entry has since been corrected in place. (Corrected 2026-09-05; see [Unreleased].)
+
 ## [7.0.0-rc.1] - 2026-08-28
 
 ### Added
@@ -86,7 +174,7 @@ and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2
 - Tool responses keep their typed error envelopes when SQLite is unavailable: input validation still returns `ERR_INVALID_INPUT`, database-independent tools such as the NBT utilities still return results, and a metrics-recording failure no longer replaces a completed response.
 - The server recovers from a crashed worker instead of going unresponsive. A worker that hit a fatal `uncaughtException` or `unhandledRejection` used to stay alive with recovery bypassed; it now exits so the supervisor can replace it. A restart blocked by stale process-tree cleanup is retried with capped backoff instead of waiting for shutdown.
 - The server no longer leaves orphaned processes behind. A keep-alive timer kept the worker's event loop running after stdin closed, so any launcher that terminated the server without a cooperative shutdown left a resident node process — about 125 MB on the reference host — and each restart added another. The worker now stands down on stdin EOF, and also when the parent process it recorded at startup disappears. Replies still being written after a half-close are delivered in full. A host that immediately closes every child's stdin now backs off exponentially instead of respawning a worker ten times a second, while a genuine crash still gets a prompt replacement. Measured on the reference host over one full test run each way: 20 orphaned workers before the fix, 0 after.
-- Ending the session no longer leaves a worker process behind. `SIGHUP` — what a terminating launcher or a vanishing session sends — was never handled, and an uncaught error in the supervisor went to node's default handler, so either one left the detached worker process group with nobody to collect it. Both now run the ordinary shutdown path, report a `supervisor.fatal` event where applicable, and exit non-zero once the worker group is collected or a bounded watchdog expires.
+- Ending the session no longer leaves a worker process behind. `SIGHUP` — what a terminating launcher or a vanishing session sends — was never handled, and an uncaught error in the supervisor went to node's default handler, so either one left the detached worker process group with nobody to collect it. Both now run the ordinary shutdown path and collect that group before the process leaves, and the exit code says which of the two happened: `SIGHUP` is an ordinary cooperative stop and exits with code 0, exactly as when stdin closes, while an uncaught supervisor fault reports a `supervisor.fatal` event and exits non-zero once the worker group is collected or a bounded watchdog expires — so a launcher can tell a crash from a clean stop. (Corrected 2026-09-05; see [Unreleased].)
 - The published package no longer risks shipping internal design documents. `files` listed `docs/**/*.md`, and because an npm `files` allowlist overrides `.gitignore`, a publish from a working tree containing local design notes would have included them. `files` now names the three intended documents explicitly.
 - The automated npm release workflow can no longer publish a prerelease under the `latest` dist-tag: it derives the dist-tag from the package version, so a SemVer prerelease publishes under `rc` and an install without an explicit tag never picks up a release candidate.
 

package/README.md

@@ -172,8 +172,10 @@ These notes cover high-frequency decisions during onboarding. For the full pitfa
 - `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-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. Set `VALIDATE_PROJECT_TASKS_OFF=1` to omit the additive `tasks` field.
+- `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.
+- Artifact downloads are capped at 512 MiB (`536870912` bytes) each. Set `MCP_MAX_DOWNLOAD_BYTES` to an ASCII-decimal byte count to override it; values below 1 MiB are raised to 1 MiB, and anything else — non-numeric, malformed, or too large to be an exact integer — falls back to the default. The cap is checked twice: against `Content-Length` before any body is read (a header that is not a plain byte count is treated as absent rather than as a breach), and against the bytes actually received, so a chunked or mis-declared response is caught too. A download that exceeds it fails with `ERR_LIMIT_EXCEEDED` and is not retried; the partial file is deleted on a best-effort basis, so a file the server cannot remove may survive the refusal. A cached copy is never served in its place — a cap is a configuration verdict, not a passing outage, and standing a stale artifact in for it would hide the ceiling instead of reporting it. When every repository trips the cap, the terminal `ERR_REPO_FETCH_FAILED` reports it where a caller can actually read it: `hints` carries the sentence naming `MCP_MAX_DOWNLOAD_BYTES` and the byte count to clear, and `context.repoFailureCode` is `ERR_LIMIT_EXCEEDED`.
+- Nested (Jar-in-Jar) entries are capped at 64 MiB (`67108864` bytes) of uncompressed data each. Set `MCP_MAX_NESTED_JAR_ENTRY_BYTES` to override it, on the same rules as the download cap: ASCII decimal digits, values below 1 MiB raised to 1 MiB, anything else falling back to the default. The size is checked against the entry's declared uncompressed size before the read starts and again against the bytes actually streamed. A breach fails that one inner jar with `ERR_LIMIT_EXCEEDED`; the shell jar's other inner jars still resolve.
 - Queued calls resume only after the replacement worker completes initialization replay. If replacement startup or replay fails, queued tool calls terminate with `ERR_WORKER_RESTART` instead of waiting indefinitely. If unresolved process-tree cleanup fills the supervisor's two live-generation slots, new requests fail with the existing restart envelope and unavailable notifications are warning-dropped until cleanup or reconnect. On POSIX, an already-gone process group counts as cleaned up rather than leaving a stale cleanup token.
 - If a workspace was built with `GRADLE_USER_HOME=/tmp/...` or another isolated Gradle home, pass that path as `gradleUserHome` so source, mapping, runtime, and project validation lookups use the same Loom cache instead of stale caches under the MCP process home.
 - `manage-cache` reports corrupt Mojang binary-remap cache directories under `cacheKinds: ["binary-remap"]` with `status: "corrupt"`, and can delete them by `selector.artifactId` in preview/apply workflows.

package/dist/artifact-identity.d.ts

@@ -0,0 +1,130 @@
+import type { MappingVariant } from "./types.js";
+/**
+ * The single owner of artifact identity: what an artifactId is derived from,
+ * and how the derived signature is composed into the id.
+ *
+ * Five call sites produce a jar id - three in `src/source-resolver.ts` and two
+ * in `src/source/artifact-resolver.ts` - and every one of them reaches it
+ * through {@link jarArtifactIdentity}, so the derivation is written once. The
+ * coordinate cascade's five results are composed by {@link composeArtifactId},
+ * which is the only place either id layout appears.
+ *
+ * Both id spaces derive the same way: a sha256 of the bytes of the file the id
+ * is about, produced by {@link contentSignature}. Neither composer takes a bare
+ * `signature: string`, and the one signature type there is can only be built
+ * from a value tagged as a content digest, so nothing cheaper can reach the
+ * hash by a route nobody reviewed.
+ */
+/** A sha256 of the bytes of the file itself. */
+export interface ContentDigestSignature {
+    readonly from: "content-digest";
+    readonly value: string;
+}
+export declare function contentDigestSignature(value: string): ContentDigestSignature;
+/**
+ * An id for a jar named by its path.
+ *
+ * The layout is `jar | <path> | <signature> | source`, plus `mojang-remapped`
+ * when that variant applies. The trailing `source` is a constant part of the
+ * layout with no producer that varies it; it is written out because the digest
+ * depends on every part.
+ */
+export interface JarArtifactIdSpec {
+    readonly space: "jar";
+    /** Symlink-resolved, so two names for one file cannot mint two ids. */
+    readonly jarPath: string;
+    /**
+     * A sha256 of the jar's bytes, the same kind of signature the coordinate
+     * space takes. Required rather than merely permitted: a producer cannot
+     * identify a jar by something cheaper without changing this type.
+     */
+    readonly signature: ContentDigestSignature;
+    /**
+     * Appended to the signature after a `:` before hashing. The decompile route
+     * is the only user: the same jar read for its sources and the same jar handed
+     * to the decompiler are different artifacts and must not share an id.
+     */
+    readonly signatureQualifier?: string;
+    readonly mappingVariant?: MappingVariant;
+}
+/**
+ * An id for an artifact reached through a Maven coordinate.
+ *
+ * The layout is `coord | <coordinate> | <idSource> | <signature>`, plus
+ * `mojang-remapped` when that variant applies.
+ *
+ * The signature is a content digest of the bytes this cascade resolved, the
+ * same as the jar space's.
+ */
+export interface CoordinateArtifactIdSpec {
+    readonly space: "coordinate";
+    readonly coordinate: string;
+    /**
+     * The id space this resolution belongs to, so artifacts discovered along
+     * different paths cannot collide in the hash.
+     */
+    readonly idSource: string;
+    readonly signature: ContentDigestSignature;
+    readonly mappingVariant?: MappingVariant;
+}
+export type ArtifactIdSpec = JarArtifactIdSpec | CoordinateArtifactIdSpec;
+/**
+ * The qualifier the decompile route puts on a jar's signature. Shared so the
+ * full resolve and the lightweight probe cannot spell it differently and mint
+ * two ids for one decompiled jar.
+ */
+export declare const DECOMPILE_SIGNATURE_QUALIFIER = "decompile";
+/** Compose an artifactId. The only place either id layout is written down. */
+export declare function composeArtifactId(spec: ArtifactIdSpec): string;
+export interface JarArtifactIdentity {
+    /** The symlink-resolved path the signature was read from and the id composed from. */
+    readonly resolvedPath: string;
+    /** The signature as published in `ResolvedSourceArtifact.artifactSignature`, qualifier included. */
+    readonly signature: string;
+    readonly artifactId: string;
+}
+export interface JarArtifactIdentityOptions {
+    readonly signatureQualifier?: string;
+    readonly mappingVariant?: MappingVariant;
+}
+/**
+ * Normalize, derive, compose - in that order, for every jar-route producer.
+ *
+ * Normalizing first is what makes one jar under two names one artifact: the
+ * path that enters the hash is the resolved one, never the one handed in.
+ * `tests/source-service/probe-resolve-id-agreement.test.ts` pins that the
+ * lightweight probe and a full resolve agree through a symlinked directory.
+ *
+ * The derivation is {@link contentSignature}, so a jar named by path is
+ * identified by what is inside it: moving its mtime without changing a byte
+ * leaves the id where it was, and replacing its bytes moves the id.
+ *
+ * Hashing reads the whole file, so every producer calls this on its own branch,
+ * on the one file that branch's id is about, rather than once before the branch
+ * is picked. The branch that adopts a sibling `-sources.jar` therefore hashes
+ * that sibling and not the binary beside it, and the branch that finds no
+ * sources and cannot decompile hashes nothing at all.
+ */
+export declare function jarArtifactIdentity(jarPath: string, options?: JarArtifactIdentityOptions): Promise<JarArtifactIdentity>;
+/**
+ * The identity of a jar sitting on local disk: a sha256 of its bytes.
+ *
+ * This is the derivation behind every artifactId this module composes - the
+ * coordinate cascade's local legs call it directly, and the jar route reaches
+ * it through {@link jarArtifactIdentity}.
+ *
+ * `~/.m2` and the Gradle module cache move a file's mtime for reasons that have
+ * nothing to do with its contents - an eviction followed by a re-fetch of
+ * byte-identical bytes, a filesystem restore, a plain `touch`. An `mtimeMs:size`
+ * signature turns every one of those into a fresh artifactId and a fresh
+ * decompile, which is exactly the instability the download cache's
+ * content-addressed identity removed from the remote half of the coordinate
+ * cascade.
+ *
+ * Hashing is not free and that cascade is re-walked on every target-driven tool
+ * call, so the digest is memoized against the stat that produced it. The stat is
+ * taken *before* the digest on purpose: bytes replaced mid-hash are recorded
+ * against a stat they no longer have, so the entry is rejected on the next call
+ * and re-derived - a wasted hash, never a wrong identity.
+ */
+export declare function contentSignature(jarPath: string): Promise<ContentDigestSignature>;

package/dist/artifact-identity.js

@@ -0,0 +1,142 @@
+import { statSync } from "node:fs";
+import { stableArtifactId } from "./config.js";
+import { normalizeJarPath } from "./path-resolver.js";
+import { digestFile } from "./repo-downloader.js";
+export function contentDigestSignature(value) {
+    return { from: "content-digest", value };
+}
+/**
+ * The qualifier the decompile route puts on a jar's signature. Shared so the
+ * full resolve and the lightweight probe cannot spell it differently and mint
+ * two ids for one decompiled jar.
+ */
+export const DECOMPILE_SIGNATURE_QUALIFIER = "decompile";
+function qualifySignature(value, qualifier) {
+    return qualifier === undefined ? value : `${value}:${qualifier}`;
+}
+/** Compose an artifactId. The only place either id layout is written down. */
+export function composeArtifactId(spec) {
+    const parts = spec.space === "jar"
+        // "jar" and "coord" are the tokens that enter the hash. They are not the
+        // `space` discriminant values, which only pick the layout.
+        ? ["jar", spec.jarPath, qualifySignature(spec.signature.value, spec.signatureQualifier), "source"]
+        : ["coord", spec.coordinate, spec.idSource, spec.signature.value];
+    if ((spec.mappingVariant ?? "pass") === "mojang-remapped") {
+        parts.push("mojang-remapped");
+    }
+    return stableArtifactId(parts);
+}
+/**
+ * Normalize, derive, compose - in that order, for every jar-route producer.
+ *
+ * Normalizing first is what makes one jar under two names one artifact: the
+ * path that enters the hash is the resolved one, never the one handed in.
+ * `tests/source-service/probe-resolve-id-agreement.test.ts` pins that the
+ * lightweight probe and a full resolve agree through a symlinked directory.
+ *
+ * The derivation is {@link contentSignature}, so a jar named by path is
+ * identified by what is inside it: moving its mtime without changing a byte
+ * leaves the id where it was, and replacing its bytes moves the id.
+ *
+ * Hashing reads the whole file, so every producer calls this on its own branch,
+ * on the one file that branch's id is about, rather than once before the branch
+ * is picked. The branch that adopts a sibling `-sources.jar` therefore hashes
+ * that sibling and not the binary beside it, and the branch that finds no
+ * sources and cannot decompile hashes nothing at all.
+ */
+export async function jarArtifactIdentity(jarPath, options = {}) {
+    const resolvedPath = normalizeJarPath(jarPath);
+    const signature = await contentSignature(resolvedPath);
+    return {
+        resolvedPath,
+        signature: qualifySignature(signature.value, options.signatureQualifier),
+        artifactId: composeArtifactId({
+            space: "jar",
+            jarPath: resolvedPath,
+            signature,
+            signatureQualifier: options.signatureQualifier,
+            mappingVariant: options.mappingVariant
+        })
+    };
+}
+/**
+ * Digests already derived from a local jar, each pinned to the stat that
+ * produced it.
+ *
+ * Keyed by the symlink-resolved path, so a jar reached through two names is
+ * hashed once. The entry is only ever *reused*, never trusted on its own: it is
+ * discarded unless size, mtimeMs, inode and ctimeMs all still match the file on
+ * disk. ctimeMs is in that key because it is the field a write moves that
+ * `utimes` cannot put back, so a same-size replacement carrying a restored
+ * mtime is re-hashed rather than served the digest of the bytes it replaced.
+ *
+ * Known limitation: that guarantee is only as strong as the platform's
+ * inode-change timestamp. Where a filesystem does not advance ctimeMs on a
+ * write, this key degrades to size + mtime + inode and a same-size replacement
+ * whose mtime was restored is served the recorded digest until the entry is
+ * evicted. Nothing here re-reads the bytes to check.
+ *
+ * Bounded, like the helper caches in `src/source/artifact-resolver.ts`: this map
+ * is module-level and lives as long as the process, and a long-running server
+ * walks the resolution cascade once per target-driven tool call, so an
+ * unbounded map grows with every distinct jar path the server has ever seen.
+ * Eviction costs at most one re-hash, which is exactly what a cache miss
+ * already costs.
+ */
+const contentSignatureCache = new Map();
+const MAX_CONTENT_SIGNATURE_CACHE = 512;
+/** Insert, dropping the oldest key first when the bound is reached. */
+function rememberContentSignature(resolvedPath, entry) {
+    if (!contentSignatureCache.has(resolvedPath) && contentSignatureCache.size >= MAX_CONTENT_SIGNATURE_CACHE) {
+        const oldestKey = contentSignatureCache.keys().next().value;
+        if (oldestKey) {
+            contentSignatureCache.delete(oldestKey);
+        }
+    }
+    contentSignatureCache.set(resolvedPath, entry);
+}
+/**
+ * The identity of a jar sitting on local disk: a sha256 of its bytes.
+ *
+ * This is the derivation behind every artifactId this module composes - the
+ * coordinate cascade's local legs call it directly, and the jar route reaches
+ * it through {@link jarArtifactIdentity}.
+ *
+ * `~/.m2` and the Gradle module cache move a file's mtime for reasons that have
+ * nothing to do with its contents - an eviction followed by a re-fetch of
+ * byte-identical bytes, a filesystem restore, a plain `touch`. An `mtimeMs:size`
+ * signature turns every one of those into a fresh artifactId and a fresh
+ * decompile, which is exactly the instability the download cache's
+ * content-addressed identity removed from the remote half of the coordinate
+ * cascade.
+ *
+ * Hashing is not free and that cascade is re-walked on every target-driven tool
+ * call, so the digest is memoized against the stat that produced it. The stat is
+ * taken *before* the digest on purpose: bytes replaced mid-hash are recorded
+ * against a stat they no longer have, so the entry is rejected on the next call
+ * and re-derived - a wasted hash, never a wrong identity.
+ */
+export async function contentSignature(jarPath) {
+    // The same normalization the jar route applies, kept so this path still
+    // refuses a vanished or non-jar file the way it always has.
+    const resolvedPath = normalizeJarPath(jarPath);
+    const stats = statSync(resolvedPath);
+    const cached = contentSignatureCache.get(resolvedPath);
+    if (cached &&
+        cached.mtimeMs === stats.mtimeMs &&
+        cached.size === stats.size &&
+        cached.ino === stats.ino &&
+        cached.ctimeMs === stats.ctimeMs) {
+        return contentDigestSignature(cached.sha256);
+    }
+    const { contentSha256 } = await digestFile(resolvedPath);
+    rememberContentSignature(resolvedPath, {
+        mtimeMs: stats.mtimeMs,
+        size: stats.size,
+        ino: stats.ino,
+        ctimeMs: stats.ctimeMs,
+        sha256: contentSha256
+    });
+    return contentDigestSignature(contentSha256);
+}
+//# sourceMappingURL=artifact-identity.js.map

package/dist/cache-registry.d.ts

@@ -45,6 +45,16 @@ export declare function pathContainsVersion(path: string, version: string): bool
 export type CacheRegistryConfig = {
     cacheDir: string;
     sqlitePath: string;
+    /**
+     * SQLite page-cache and memory-map tuning for the artifact index, as
+     * MCP_SQLITE_CACHE_KB and MCP_SQLITE_MMAP_SIZE resolve them. Optional because
+     * a caller with no opinion should get the same defaults `applyPragmas` gives
+     * every other reader of the index - but a caller that HAS one is the whole
+     * point: without these the registry opened the index on the built-in defaults,
+     * so the two variables tuned every consumer except manage-cache.
+     */
+    sqliteCacheKb?: number;
+    sqliteMmapSize?: number;
     pathRuntimeInfo?: PathRuntimeInfo;
     workspaceContextCache?: WorkspaceContextCache;
 };

package/dist/cache-registry.js

@@ -227,7 +227,11 @@ function openDb(config) {
     if (!existsSync(config.sqlitePath)) {
         return undefined;
     }
-    return openDatabase(config).db;
+    return openDatabase({
+        sqlitePath: config.sqlitePath,
+        sqliteCacheKb: config.sqliteCacheKb,
+        sqliteMmapSize: config.sqliteMmapSize
+    }).db;
 }
 function candidatePathsForEntry(entry) {
     const paths = new Set();

package/dist/config.js

@@ -229,8 +229,8 @@ export function buildArtifactAlias(input) {
     else {
         tokens.push("jar", aliasJarBase(input.value));
     }
-    // mappingVariant is canonical — `artifactIdForJar` / `artifactIdForCoordinate`
-    // bake "mojang-remapped" into the artifactId, so the same artifactId always
+    // mappingVariant is canonical — `composeArtifactId` in `src/artifact-identity.ts`
+    // bakes "mojang-remapped" into the artifactId, so the same artifactId always
     // produces the same alias regardless of how many times resolveArtifact is
     // called. The token here is purely a human-readable hint; the 12-char hash
     // suffix would already separate remapped artifacts from pass-through ones.

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

@@ -3,8 +3,8 @@ import { z } from "zod";
 export declare const analyzeModShape: {
     task: z.ZodEnum<{
         search: "search";
-        summary: "summary";
         decompile: "decompile";
+        summary: "summary";
         "class-source": "class-source";
         members: "members";
         remap: "remap";
@@ -22,8 +22,8 @@ export declare const analyzeModShape: {
         class: "class";
         field: "field";
         method: "method";
-        all: "all";
         content: "content";
+        all: "all";
     }>>;
     limit: z.ZodDefault<z.ZodNumber>;
     includeFiles: z.ZodDefault<z.ZodBoolean>;
@@ -51,8 +51,8 @@ export declare const analyzeModShape: {
 export declare const analyzeModSchema: z.ZodObject<{
     task: z.ZodEnum<{
         search: "search";
-        summary: "summary";
         decompile: "decompile";
+        summary: "summary";
         "class-source": "class-source";
         members: "members";
         remap: "remap";
@@ -70,8 +70,8 @@ export declare const analyzeModSchema: z.ZodObject<{
         class: "class";
         field: "field";
         method: "method";
-        all: "all";
         content: "content";
+        all: "all";
     }>>;
     limit: z.ZodDefault<z.ZodNumber>;
     includeFiles: z.ZodDefault<z.ZodBoolean>;

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

@@ -2,8 +2,8 @@ import { z } from "zod";
 import type { CheckSymbolExistsOutput, FindMappingOutput, GetClassApiMatrixOutput, ResolveMethodMappingExactOutput, ResolveWorkspaceSymbolOutput, TraceSymbolLifecycleOutput } from "../source-service.js";
 export declare const analyzeSymbolShape: {
     task: z.ZodEnum<{
-        map: "map";
         workspace: "workspace";
+        map: "map";
         exists: "exists";
         "exact-map": "exact-map";
         lifecycle: "lifecycle";
@@ -72,8 +72,8 @@ export declare const analyzeSymbolShape: {
 };
 export declare const analyzeSymbolSchema: z.ZodObject<{
     task: z.ZodEnum<{
-        map: "map";
         workspace: "workspace";
+        map: "map";
         exists: "exists";
         "exact-map": "exact-map";
         lifecycle: "lifecycle";

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

@@ -48,6 +48,14 @@ 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.
+                    artifactSelectedBy: input.target.kind === "jar" ? "caller" : "tool",
                     className: entry.className,
                     access: entry.access,
                     includeSynthetic: entry.includeSynthetic,

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

@@ -5,10 +5,10 @@ export declare const detailSchema: z.ZodEnum<{
     full: "full";
 }>;
 export declare const includeGroupSchema: z.ZodEnum<{
-    entries: "entries";
     workspace: "workspace";
-    candidates: "candidates";
+    entries: "entries";
     source: "source";
+    candidates: "candidates";
     warnings: "warnings";
     registry: "registry";
     preview: "preview";