@adhisang/minecraft-modding-mcp 4.2.1 → 6.0.0

package/CHANGELOG.md

@@ -5,6 +5,75 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [6.0.0] - 2026-06-25
+
+### Changed
+
+- **Breaking:** tool responses omit `meta.warnings` entirely when there are no warnings (previously always emitted as `[]`), and omit `meta.detailApplied` when it equals the tool's default detail level (entry tools: `summary`; expert/batch tools: their per-tool default). Clients must treat a missing `meta.warnings` as "no warnings" and a missing `meta.detailApplied` as "the default detail was applied". `meta.includeApplied` semantics are unchanged (already omitted when empty).
+- `tools/list` payload slimmed by ~12% (93.2 KB → 82.2 KB, roughly 2,700 fewer tokens held in an agent's context): parameter descriptions that merely echoed enum values (e.g. `"obfuscated | mojang | intermediary | yarn"`) are removed since the JSON Schema `enum` already carries them, the shared `detail`/`include`/`target`/`scope`/`gradleUserHome` descriptions are tightened, the expert-tool steering note is shortened, and the longest tool descriptions (`resolve-method-mapping-exact`, `get-class-source`, `get-class-members`, the `batch-*` family) no longer repeat information already present in their input schemas. Wording-only — no input shapes, defaults, or validation rules changed.
+- Per-member remap-failure warnings are aggregated into a single line per namespace direction (e.g. `Could not remap 12 methods from obfuscated to mojang (foo, bar, baz, +9 more).`) instead of one line per member, and the structured `meta.warningDetails[]` companion is capped to a representative set (5 entries) at `detail: "summary"` (the full text still lives in `meta.warnings[]`, so each kept entry's `index` still dereferences it). On unobfuscated versions a single core class could previously emit hundreds of near-identical remap-warning lines — the dominant token sink for those responses.
+
+### Fixed
+
+- `validate-mixin` / mixin parsing: `@Mixin(My$GeneratedClass.class)` class-literal targets containing `$` (a legal Java identifier character) are now captured as the full class name; previously the target regex started the capture mid-name and produced a wrong target.
+- **Unobfuscated Minecraft versions (26.1+):** `get-class-members` / `get-class-source` no longer mislabel the already-deobfuscated runtime namespace as `obfuscated` for a `mapping: "mojang"` request when reusing a previously-resolved artifact. The mislabel made `requestedMapping ("mojang") !== mappingApplied ("obfuscated")`, which triggered a doomed mojang↔obfuscated remap that dropped every member (forcing a spurious `decompiledFallback`), disabled `memberPattern`, and flooded the response with per-member remap warnings. The namespace is now reconciled to `mojang` (identity), so members come back from bytecode with correct names, `memberPattern` applies, and the warning flood disappears.
+- **`batch-symbol-exists` / `check-symbol-exists` on unobfuscated versions:** method existence checks returned `not_found` for methods that genuinely exist, because the empty mapping graph reported `not_found` and skipped the runtime-bytecode fallback. The fallback now runs for `not_found` method queries; name-only lookups resolve when any overload matches (no longer reported as `ambiguous` for an existence check), and inherited methods are included (`level.getGameTime()` resolves on `Level`).
+- `check-symbol-exists`: a class genuinely absent from the runtime jar now yields a clear `… was not found in the Minecraft <version> runtime jar` message instead of a generic load-failure note.
+- `resolve-artifact`: a decompilation failure (`ERR_DECOMPILER_FAILED`) no longer advertises an `artifactId` for an artifact that was never persisted — the leaked id previously caused a follow-up `find-class` / `get-class-*` to fail with "Artifact not found. Resolve context first."
+- Workspace dependency version detection falls back to the umbrella package's version property (e.g. `fabricApiVersion` / `fabric_api_version`) for submodules that don't declare their own (e.g. `net.fabricmc.fabric-api:fabric-screen-handler-api-v1`), instead of failing with `ERR_DEPENDENCY_VERSION_UNRESOLVED`. The submodule's own property still takes precedence when present.
+- `get-class-source` now honors an explicit `mapping` argument instead of forcing the artifact's stored namespace (matching `get-class-members`), so a `className` supplied in a declared namespace no longer fails with `CLASS_NOT_FOUND`. Several recovery `suggestedCall`s are corrected: the snippet continuation no longer drops the default `maxLines` (which produced an unbounded follow-up read), the `decompiledFallback` truncation flag is reported accurately, and a hardcoded `"latest"` version that `resolve-artifact` rejects is replaced with the concrete resolved version. A method query with an omitted `signatureMode` is treated as a non-exact match in the runtime check (descriptorless methods are no longer guaranteed `not_found`), binary jars are remapped from the source jar (not the absent output) after an index loss, the `globToSqlLike` `**` push-down no longer drops direct children, the vanilla-jar fallback no longer retains the named-signature mapping, and the workspace-context write-back is serialized so it stops racing dependency-target synthesis.
+- `resolve-method-mapping-exact` mirrors `find-mapping`'s obfuscated-namespace acceptance set, so a single-hop `intermediary → yarn` lookup whose candidate carries an obfuscated-namespace descriptor no longer returns a false `not_found`. Loading yarn Tiny pairs from Maven no longer unions three builds (or fetches unusable v1 jars), removing the spurious `ambiguous` results that produced. Tiny caches (`extractTinyFromJar` / `resolveMojangTinyFile`) are now written atomically (temp file + `rename`) so a crash mid-write cannot leave a truncated `.tiny` behind a permanent `existsSync` fast path, and `get-class-api-matrix` keys its cursor context on `gradleUserHome` so a cursor minted against one dependency graph cannot replay against another.
+- `validate-mixin` / mixin parsing no longer matches the word `class` inside comments or javadoc (which yielded a wrong `className`) and no longer parses annotations inside block comments (which produced phantom `@Shadow` / `@Accessor` members and false definite errors); both passes now skip comment regions. The injection-point wildcard quantifier is anchored so an exact-match target no longer triggers a false positive.
+- `search-class-source` / file search no longer re-emits `both`-tier hits as duplicate `content`-tier hits on later pages (they are deduped across the cursor), escapes the `LIKE` needle in path search, push-down, and count queries so the declared `ESCAPE` clause actually applies, and stops returning a `nextCursor` on the final partial page (which previously forced an extra empty-page fetch).
+- `inspect-minecraft`: `task: "versions"` no longer drops the entire `versions` block at the default detail level, and `task: "file"` content is reachable now that `file` is a valid `include` group. `task: "api-overview"` honors `maxRows` and flags truncation instead of silently capping the matrix at 25 rows while reporting `rowsTruncated: false`. The `file` / `search` / `list-files` tasks return the friendly "blocked" summary (carrying the version-inference warning) instead of forwarding an empty `artifactId`, `task: "workspace"` no longer passes the literal `"unknown"` as the Minecraft version, the `get-class-members` truncation `nextAction` raises the member limit so the suggested retry no longer reproduces the same cut, and the `remap-mod-jar` preview `nextAction` preserves an explicit `outputJar`.
+- stdio supervisor: a supervisor-replayed `initialize` no longer emits a stray error response when the worker crashes again after the client is already initialized; a worker spawn error that previously stalled the supervisor permanently now recovers; and a stale worker exit no longer detaches and orphans the replacement worker. The Java subprocess runner drains trailing stdout/stderr before resolving on child exit, so the final output is no longer lost.
+- NBT JSON Patch: an `add` / `replace` op with key `__proto__` is assigned as an own enumerable property instead of silently mutating the prototype and dropping the member. Non-finite floats round-trip correctly — decode emits a sentinel string rather than a raw number, and the typed-JSON layer no longer rejects otherwise-valid NBT containing `NaN` / `Infinity`.
+- Data generation no longer deadlocks once the child's stdout pipe buffer fills (the output is now drained), the download timeout now covers the response body stream instead of being cleared after headers (removing an indefinite hang), and concurrent identical `remap-mod-jar` calls no longer race on a non-atomic cache copy.
+- Access Widener parsing accepts valid `transitive-` kinds — the prefix is stripped, the base kind validated, and transitivity recorded on the entry — instead of rejecting them as unknown. Path conversion recognizes the `wsl.localhost` UNC form (not only `wsl$`) and rejects a UNC WSL path that targets a different distro than the server runs in, instead of silently mapping it.
+- `validate-mixin` recovery suggestions no longer read `input.path` before checking the mode (which turned a project-mode call into an executable path-mode `suggestedCall`), and the access-transformer suggestion no longer hardcodes the access-widener subject kind. The `batch-class-source` `outputFile` dedupe guard canonicalizes paths unconditionally so absolute-path aliases (`/a/../b`, `//a`) collide as intended and cannot race `writeFile` on the same inode.
+
+### Performance
+
+- SQLite repositories cache prepared statements for dynamically built queries (cursor-paginated symbol/file lookups, scoped symbol search, count queries, `IN (...)`-list lookups) in a small per-repo LRU instead of re-preparing the SQL on every call.
+- Symbol search with regex/glob/package filters now streams rows from SQLite instead of materializing every symbol of the artifact in memory first; only matching rows are retained.
+- Cache-registry operations no longer read and JSON-parse every registry file from disk on each call; the parsed registry state is cached and invalidated on write.
+- `get-class-members` / `get-class-source` no longer re-strip the whole decompiled file once per nested type when extracting members (`extractDecompiledMembers` was quadratic in the nested-type count).
+- NBT patch validation revalidates only the touched subtree per patch op instead of the whole document (previously quadratic), and the array encoders reuse a single buffer cursor instead of allocating a `Buffer` per scalar write.
+- `check-symbol-exists` indexes its lookups instead of scanning the full target namespace on every call.
+
+## [5.0.0] - 2026-06-04
+
+### Changed
+
+- **Breaking:** `get-class-members` now returns at most **150** members per page by default (was 500). The existing `nextCursor` continuation already covers paging; callers that need more in one response can pass an explicit `maxMembers` (still capped at 5000). `maxClassResults` and `maxVersions` defaults are unchanged.
+- **Breaking:** `inspect-minecraft` responses no longer echo the requested subject inside `summary.subject`. The raw requested subject still surfaces exactly once, in the always-on top-level `subject` block as `subject.requested` (paired with `subject.resolved`). Clients reading `summary.subject.requested` must switch to `subject.requested` (or correlate via `requestId`).
+- **Breaking:** `meta.warningDetails[]` entries no longer duplicate the warning text. Each entry now carries `index: number` referencing its string in `meta.warnings[]` (1:1, order-preserving) instead of a `message` field. Clients reading `warningDetails[].message` must switch to `meta.warnings[detail.index]`.
+- **Breaking:** `get-class-source` and `get-class-members` now omit the diagnostic fields `provenance`, `qualityFlags`, and `artifactContents` by default. Pass the new `includeProvenance: true` to include them. (`compact` keeps its existing meaning — strip empty fields, and for `get-class-members` also `context`.) Callers that previously read those fields without setting `compact` must now pass `includeProvenance: true`.
+- **Breaking:** `get-class-members` member objects are slimmed on the wire. `accessFlags` is dropped (the modifiers are already encoded in `javaSignature`), `isSynthetic` is emitted only when `true`, and `ownerFqn` is hoisted to a single block-level `members.ownerFqn` when every member shares one owner (the common, non-`includeInherited` case); it stays per-member when `includeInherited` surfaces multiple owners. `name` and `javaSignature` are unchanged. Read the owner from `members.ownerFqn` (falling back to `member.ownerFqn`), and derive access modifiers from `javaSignature` instead of `accessFlags`. `diff-class-signatures` / `verify-mixin-target` member shapes are unchanged.
+- **Breaking:** `get-class-members` omits `jvmDescriptor` on **field** members by default (the type is already in `javaSignature`). Method/constructor `jvmDescriptor` is always present for overload disambiguation. Pass `includeDescriptors: true` (legacy `get-class-members`) or `include: ["descriptors"]` (`inspect-minecraft` task=`class-members`) to also emit field descriptors.
+- **Breaking:** `analyze-symbol` (and the `inspect-minecraft`-adjacent mapping flows `exists`/`map`/`exact-map`/`workspace`) now reuse the expert-tool candidate projection: when a lookup resolves to a single exact candidate that just duplicates `match`, the `candidates` block is omitted; for unresolved results with more than three candidates the tail is slimmed and `candidateDetailsTruncated: true` is surfaced. Read the resolved symbol from `match` rather than `candidates[0]`.
+- **Breaking:** `validate-mixin` (and `validate-project` task=`mixin`/`project-summary`) now default `reportMode` to `summary-first` (was `full`) — for every caller, not just the MCP wire boundary. The default response hoists shared provenance/warnings/incomplete reasons and omits per-result `resolvedMembers`, `toolHealth`, `structuredWarnings`, `aggregatedWarnings`, and `confidenceBreakdown`; `summary`, `issues`, `issueSummary`, and top-level provenance/toolHealth are retained. Pass `reportMode="full"` or `explain=true` to restore per-result `resolvedMembers`/`toolHealth`/`resolutionTrace`. `explain=true` now also preserves `resolutionTrace` under `reportMode="compact"`.
+- `verify-mixin-target`: `member.descriptor` now accepts empty / whitespace-only strings as "omitted" (normalized to `undefined`), matching every other optional descriptor field on the surface. Previously rejected with `ERR_INVALID_INPUT`. Non-breaking — no change for callers passing a real descriptor.
+- **Breaking:** `get-class-source` and `get-class-members` now take the same `kind`-based `target` shape as `resolve-artifact`: `target: { kind: "version"|"jar"|"coordinate"|"workspace"|"dependency", ... }`, plus `target: { kind: "artifact", artifactId }` to reuse an already-resolved artifact. The old `target: { type: "artifact", artifactId }` form is removed — migrate to `{ kind: "artifact", artifactId }`. The redundant `{ type: "resolve", kind, value }` wrapper is still accepted (the `type` key is now ignored), but `{ kind, value }` is the canonical shape. Published `suggestedCall` targets for these tools now use the `kind`-based shape.
+- **Breaking:** `analyze-symbol` `task="lifecycle"` gains explicit range controls `fromVersion`, `toVersion`, `maxVersions`, `includeTimeline`, and `includeSnapshots` (accepted only for `task="lifecycle"`; supplying them on another task is now rejected instead of silently ignored). The existing `version` field is kept as a back-compat alias for `toVersion` (range end; `toVersion` takes precedence). **Behavior change:** the lifecycle scan default grew from the previous hard-coded **5 versions** to the service default of **120** (clamped at 400) — pass `maxVersions: 5` to restore the old window. A lifecycle request still requires an end anchor (`version` or `toVersion`).
+- `analyze-symbol` `subject.kind="symbol"` is now real selector-based auto-detect (owner+descriptor ⇒ method, owner only ⇒ field, otherwise ⇒ class) with the inferred kind surfaced as a warning and documented via the schema `describe()`. Previously `"symbol"` was silently coerced to `class` (exists/map/workspace), rejected (api-overview), or ignored (exact-map/lifecycle). `summary.subject.kind` now reports the resolved concrete kind instead of echoing `"symbol"`. Non-breaking — the enum keeps all four values and explicit kinds are unaffected.
+- **Breaking:** `check-symbol-exists` now defaults `signatureMode` to `name-only` (was `exact`), matching `find-mapping` so the two sibling lookup tools behave identically. A `kind="method"` query with no descriptor now matches by owner+name (resolving uniquely or reporting ambiguous overloads) instead of failing with `ERR_INVALID_INPUT`; pass `signatureMode="exact"` to require a descriptor. `find-mapping` gains a `nameMode` parameter (default `auto`, mirroring `check-symbol-exists`): `auto` accepts a dotless class name for any `sourceMapping` (previously only `obfuscated`), `fqcn` requires a fully-qualified name. `analyze-symbol`'s own `signatureMode` default is intentionally left at `exact`.
+- **Breaking:** the per-tool `compact` boolean is removed from all expert tools (`resolve-artifact`, `find-mapping`, `resolve-method-mapping-exact`, `resolve-workspace-symbol`, `check-symbol-exists`, `get-class-source`, `get-class-members`, `search-class-source`, `list-artifact-files`) and the four `batch-*` tools, replaced by the entry-tool **`detail`** (`summary` | `standard` | `full`) + **`include[]`** response contract — one response-shaping vocabulary across the whole server. Per-tool defaults keep every default response byte-identical: resolution/mapping tools + batch default `detail: "summary"` (= old `compact: true`); `get-class-source`/`get-class-members`/`search-class-source`/`list-artifact-files` default `detail: "standard"` (= old `compact: false`, post-Phase-4 diagnostic strip). **Migration:** `compact: true` → `detail: "summary"`, `compact: false` → `detail: "full"`. `include[]` opts specific field groups back in (`["provenance"]`, `["candidates"]`, `["samples"]`, `["artifact"]`, `["paths"]`, `["descriptors"]`). The Phase-4 `includeProvenance` / `includeDescriptors` flags are retained as aliases for `include: ["provenance"]` / `include: ["descriptors"]`. Expert and batch responses now also report `meta.detailApplied` / `meta.includeApplied`.
+- `resolve-method-mapping-exact` is now documented as a strict shortcut for `find-mapping` (kind=method, signatureMode=exact): its description, schema, and the README/tool-reference entries explain that it additionally requires a **complete** descriptor projection (returns `mapping_unavailable` when class references cannot all be projected, where `find-mapping`'s exact mode resolves leniently). Documentation-only — no wire, behavior, or input-schema change; the tool is retained.
+- The display caps that were previously clamped silently now emit a clamp warning so the documented contract is truthful: `list-versions` `limit` (capped at 200), `get-class-api-matrix` `maxRows` (capped at 5000), and `compare-versions` `maxClassResults` (capped at 5000) push `"<field> was clamped to <cap> from <value>."` when an over-range value is supplied (and `inspect-minecraft task="versions"` surfaces the `list-versions` warning). Non-breaking — out-of-range values still clamp and succeed; the caps are unchanged.
+- Resource read errors (`mc://…` URIs) now carry the same recovery metadata as the equivalent tool call: `retryClass` and `issueOrigin` are always present, and `hints`, `suggestedCall`, `exampleCalls`, `fieldErrors`, and `context` are surfaced whenever the underlying `AppError` supplies them (previously the resource envelope returned only `code` + `detail`). The envelope keeps its existing nested `{ error, meta }` shape and the generic `problems/resource` type/title. Additive and non-breaking for clients reading by key.
+- **Breaking:** error envelopes add a new `retryClass` value `"server"` for non-recoverable internal server faults. `ERR_INTERNAL` (sanitized programming bugs / unexpected throws, including every non-`AppError` thrown by a handler) and `ERR_DB_FAILURE` (SQLite integrity/migration failures) now report `retryClass: "server"` instead of `"transient"`, so agents stop retrying deterministic server bugs. Genuinely-transient codes are unchanged — `ERR_REPO_FETCH_FAILED`, `ERR_ARTIFACT_RESOLUTION_FAILED`, `ERR_STAGE_BUDGET_PRE_PARSE`, `ERR_LIMIT_EXCEEDED`, and `ERR_JAVA_PROCESS_FAILED` stay `"transient"`. Clients that exhaustively `switch` on `retryClass` must add a `"server"` case (treat it like `"permanent"` for retry posture: do not retry the identical call). `issueOrigin` is unchanged (`ERR_INTERNAL` stays `tool_issue`).
+
+### Fixed
+
+- `remap-mod-jar` no longer serves a stale remapped JAR after a newer Fabric **yarn** build is published for the same Minecraft version. Yarn Tiny mappings are now cached per build coordinate (`mappings/yarn/${coordinate}.tiny`) and the resolved yarn coordinate is part of the remap cache key, so a new build produces a fresh remap instead of reusing the old jar. The newest build is re-checked at most once per 24h per MC version (a small on-disk metadata marker keeps the check off the cache-hit fast path; on a Fabric Maven outage the last-known-good build is reused rather than failing). Mojang mappings are immutable per release and unaffected. `remap-mod-jar` gains an optional `forceRemap: true` to bypass the cache and re-resolve on demand. The remap pipeline version bumps (`v2`→`v3`), a one-time invalidation of previously cached remapped jars; obsolete `mappings/${version}-yarn.tiny` files can be reclaimed via `manage-cache` on the `mapping` kind.
+
+### Performance
+
+- `get-class-api-matrix` now computes per-row cross-namespace mappings only for the requested page (`maxRows`/`cursor` window) instead of the whole class on every request, so paginated/deep-page calls scale with the window rather than the full member set. `rows`, row order, `rowCount`, `nextCursor`, and `cursorIgnored` are byte-identical. **Behavior change:** on paginated calls, `warnings` (per-row ambiguity notes) and `ambiguousRowCount` now reflect only the returned page; an unpaginated call (no `maxRows`) still reports them for the whole class.
+
 ## [4.2.1] - 2026-05-23
 
 ### Fixed

package/README.md

@@ -15,7 +15,7 @@
 
 It runs over stdio and works with Claude Desktop, Claude Code, VS Code, Codex CLI, Gemini CLI, and other MCP-capable clients.
 
-**37 tools** (6 entry + 31 expert) | **7 resources** | **4 namespace mappings** | **SQLite-backed cache**
+**41 tools** (6 entry + 35 expert) | **9 resources** | **4 namespace mappings** | **SQLite-backed cache**
 
 ## Features
 
@@ -203,7 +203,8 @@ These notes cover high-frequency decisions during onboarding. For the full pitfa
     "version": "1.21.10",
     "sourceMapping": "mojang",
     "targetMapping": "intermediary",
-    "signatureMode": "name-only"
+    "signatureMode": "name-only",
+    "detail": "standard"
   }
 }
 ```
@@ -306,13 +307,13 @@ Tools for converting symbol names between namespaces and checking symbol existen
 | Tool | Purpose |
 | --- | --- |
 | `find-mapping` | Look up mapping candidates for class, field, or method symbols |
-| `resolve-method-mapping-exact` | Resolve one method mapping with strict owner, name, and descriptor matching |
+| `resolve-method-mapping-exact` | Strict shortcut for `find-mapping` (kind=method, signatureMode=exact); requires the full owner+name+descriptor triple |
 | `get-class-api-matrix` | Show one class API across `obfuscated`, `mojang`, `intermediary`, and `yarn` |
 | `resolve-workspace-symbol` | Resolve compile-visible symbol names from a Gradle workspace |
 | `check-symbol-exists` | Check whether a class, field, or method exists in a namespace |
 <!-- END GENERATED TOOL TABLE: mapping-symbols -->
 
-Several lookup tools support `compact` result shaping for shorter responses. See [docs/tool-reference.md](docs/tool-reference.md) for defaults and the full per-tool field list.
+Expert and batch tools share the `detail` (`summary` | `standard` | `full`) + `include[]` response contract for shorter responses (replacing the old per-tool `compact` flag). See [docs/tool-reference.md](docs/tool-reference.md) for per-tool defaults and the full field list.
 
 ### NBT Utilities
 

package/dist/access-transformer-parser.d.ts

@@ -1,8 +1,9 @@
 export type AccessTransformerAccessAction = "public" | "protected" | "package-private" | "private";
 export type AccessTransformerFinalAction = "add" | "remove";
+export type AccessTransformerTargetKind = "class" | "field" | "method" | "wildcard-all" | "wildcard-method";
 export type AccessTransformerEntry = {
     line: number;
-    targetKind: "class" | "field" | "method";
+    targetKind: AccessTransformerTargetKind;
     owner: string;
     target: string;
     name?: string;

package/dist/access-transformer-parser.js

@@ -19,10 +19,19 @@ function splitMemberToken(tokens) {
     if (tokens.length === 1) {
         const token = tokens[0] ?? "";
         const descriptorStart = token.indexOf("(");
+        // Wildcards: "*" targets all fields and methods; "*()" targets all methods.
+        // (Standard Forge/NeoForge AT syntax — previously parsed as a literal name.)
+        if (token === "*") {
+            return { targetKind: "wildcard-all", name: "*" };
+        }
         if (descriptorStart >= 0) {
+            const namePart = token.slice(0, descriptorStart);
+            if (namePart === "*") {
+                return { targetKind: "wildcard-method", name: "*", descriptor: token.slice(descriptorStart) };
+            }
             return {
                 targetKind: "method",
-                name: token.slice(0, descriptorStart),
+                name: namePart,
                 descriptor: token.slice(descriptorStart)
             };
         }

package/dist/access-widener-parser.d.ts

@@ -9,6 +9,7 @@
 export type AccessWidenerEntry = {
     line: number;
     kind: "accessible" | "extendable" | "mutable";
+    transitive?: boolean;
     targetKind: "class" | "method" | "field";
     target: string;
     owner?: string;

package/dist/access-widener-parser.js

@@ -40,7 +40,9 @@ export function parseAccessWidener(content) {
         }
         const kind = parts[0];
         const targetKind = parts[1];
-        if (!VALID_KINDS.has(kind)) {
+        const transitive = kind.startsWith("transitive-");
+        const baseKind = transitive ? kind.slice("transitive-".length) : kind;
+        if (!VALID_KINDS.has(baseKind)) {
             parseWarnings.push(`Line ${lineNum}: Unknown access kind "${kind}".`);
             continue;
         }
@@ -48,16 +50,17 @@ export function parseAccessWidener(content) {
             parseWarnings.push(`Line ${lineNum}: Unknown target kind "${targetKind}".`);
             continue;
         }
-        const validKind = kind;
+        const validKind = baseKind;
         const validTargetKind = targetKind;
         if (validTargetKind === "class") {
-            entries.push({ line: lineNum, kind: validKind, targetKind: validTargetKind, target: parts[2] });
+            entries.push({ line: lineNum, kind: validKind, transitive, targetKind: validTargetKind, target: parts[2] });
         }
         else if (parts.length >= 5) {
             // method/field: <kind> <targetKind> <owner> <name> <descriptor>
             entries.push({
                 line: lineNum,
                 kind: validKind,
+                transitive,
                 targetKind: validTargetKind,
                 target: parts[2],
                 owner: parts[2],

package/dist/build-suggested-call.js

@@ -6,16 +6,33 @@ function asParamsRecord(params) {
     }
     return params;
 }
-export function buildSuggestedCall(spec) {
-    if (SUGGESTED_CALL_VALIDATE_OFF) {
-        const rawParams = asParamsRecord(spec.params);
-        if (rawParams) {
-            return { suggestedCall: { tool: spec.tool, params: rawParams } };
-        }
-        return {};
+// Placeholder sentinels are `<...>` tokens that a caller must substitute before
+// the call is executable (e.g. "<version>", "<fully-qualified-class-name>").
+// The two JVM pseudo-method-names `<init>` / `<clinit>` are real, valid values
+// and are explicitly excluded so constructor lookups are not misclassified.
+const PLACEHOLDER_SENTINEL_RE = /<(?!init>)(?!clinit>)[^<>]+>/;
+function containsPlaceholderSentinel(value) {
+    if (typeof value === "string") {
+        return PLACEHOLDER_SENTINEL_RE.test(value);
+    }
+    if (Array.isArray(value)) {
+        return value.some(containsPlaceholderSentinel);
+    }
+    if (value && typeof value === "object") {
+        return Object.values(value).some(containsPlaceholderSentinel);
     }
+    return false;
+}
+export function buildSuggestedCall(spec) {
     const primaryParams = asParamsRecord(spec.params);
-    if (primaryParams) {
+    // A `suggestedCall` must be directly executable. Reject any primary payload
+    // that still carries a placeholder sentinel (e.g. "<version>") even when it
+    // is schema-valid: those belong in `exampleCalls` as templates, not as a
+    // call the caller can replay verbatim.
+    if (primaryParams && !containsPlaceholderSentinel(primaryParams)) {
+        if (SUGGESTED_CALL_VALIDATE_OFF) {
+            return { suggestedCall: { tool: spec.tool, params: primaryParams } };
+        }
         // Unknown-tool fail-open: the registry is populated at index.ts startup;
         // service-level tests that do not boot index.ts run with an empty
         // registry and rely on this pass-through. Callers that synthesize a tool
@@ -31,14 +48,18 @@ export function buildSuggestedCall(spec) {
     }
     const droppedMarker = spec.params !== undefined ? { _suggestedCallPrimaryDropped: true } : {};
     if (spec.examples && spec.examples.length > 0) {
+        // Example calls are templates (placeholders allowed) and only their
+        // schema-shape is checked. Mirror the primary path's unknown-tool
+        // fail-open so service-level tests with an unpopulated registry still
+        // surface templates instead of silently dropping them.
+        const exampleSchemaUnavailable = SUGGESTED_CALL_VALIDATE_OFF || !getToolSchema(spec.tool);
         const validated = spec.examples
             .map((example) => {
             const exampleParams = asParamsRecord(example.params);
             if (!exampleParams) {
                 return null;
             }
-            const result = validateToolParams(spec.tool, exampleParams);
-            if (!result.valid) {
+            if (!exampleSchemaUnavailable && !validateToolParams(spec.tool, exampleParams).valid) {
                 return null;
             }
             return {

package/dist/cache-registry.d.ts

@@ -34,6 +34,14 @@ type CacheEntryPage = {
     entries: CacheEntry[];
     nextCursor?: string;
 };
+/**
+ * Whether a cache entry path contains the selector version as a whole version
+ * token. Used as a fallback when an entry has no structured meta.version. The
+ * match is anchored so that a coarse selector like "1.2" does NOT match a "1.21"
+ * path (which would cause destructive prune/delete to hit the wrong caches),
+ * while still allowing major.minor sweeps where "1.21" matches "1.21.4".
+ */
+export declare function pathContainsVersion(path: string, version: string): boolean;
 export type CacheRegistryConfig = {
     cacheDir: string;
     sqlitePath: string;

package/dist/cache-registry.js

@@ -1,6 +1,7 @@
-import { existsSync, readFileSync } from "node:fs";
-import { readdir, rm, stat } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { readFile, readdir, rm, stat } from "node:fs/promises";
 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 Database from "./storage/sqlite.js";
@@ -25,6 +26,7 @@ export const CACHE_HEALTH_STATES = [
 ];
 const STALE_ENTRY_AGE_MS = 30 * 24 * 60 * 60 * 1000;
 const CURSOR_VERSION = 1;
+const CACHE_STAT_CONCURRENCY = 8;
 const STATUS_PRIORITY = ["in_use", "corrupt", "orphaned", "stale", "partial", "healthy"];
 function kindRoot(config, cacheKind) {
     switch (cacheKind) {
@@ -99,6 +101,20 @@ function inferVersion(...candidates) {
     }
     return undefined;
 }
+/**
+ * Whether a cache entry path contains the selector version as a whole version
+ * token. Used as a fallback when an entry has no structured meta.version. The
+ * match is anchored so that a coarse selector like "1.2" does NOT match a "1.21"
+ * path (which would cause destructive prune/delete to hit the wrong caches),
+ * while still allowing major.minor sweeps where "1.21" matches "1.21.4".
+ */
+export function pathContainsVersion(path, version) {
+    const escaped = version.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    // Preceding char must not be a digit or dot (avoid matching inside a longer
+    // version like 1.21 -> 21); following char must not be a digit (block
+    // 1.2 -> 1.21) but a dot is allowed so 1.21 sweeps 1.21.4.
+    return new RegExp(`(?<![\\d.])${escaped}(?!\\d)`).test(path);
+}
 function inferMapping(...candidates) {
     for (const candidate of candidates) {
         const normalized = candidate?.toLowerCase();
@@ -151,12 +167,12 @@ function inferProjectPath(pathValue, runtimeInfo) {
     }
     return undefined;
 }
-function isCorruptRegistryJson(filePath) {
+async function isCorruptRegistryJson(filePath) {
     if (!filePath.endsWith(".json")) {
         return false;
     }
     try {
-        JSON.parse(readFileSync(filePath, "utf8"));
+        JSON.parse(await readFile(filePath, "utf8"));
         return false;
     }
     catch {
@@ -228,7 +244,7 @@ function candidatePathsForEntry(entry) {
 function entryUpdatedAt(entry) {
     return typeof entry.meta?.updatedAt === "string" ? entry.meta.updatedAt : undefined;
 }
-function deriveEntryStatus(entry, config, now) {
+function deriveEntryStatus(entry, config, now, entryPathExists = false) {
     const maybeMeta = entry.meta ?? {};
     if (maybeMeta.inUse === true) {
         return "in_use";
@@ -237,7 +253,7 @@ function deriveEntryStatus(entry, config, now) {
         return "corrupt";
     }
     const candidatePaths = candidatePathsForEntry(entry);
-    const existingPaths = candidatePaths.filter((candidate) => existsSync(candidate));
+    const existingPaths = candidatePaths.filter((candidate) => (entryPathExists && candidate === entry.path) || existsSync(candidate));
     if (entry.cacheKind === "artifact-index" && !existsSync(config.sqlitePath)) {
         return "orphaned";
     }
@@ -261,10 +277,9 @@ function deriveEntryStatus(entry, config, now) {
 }
 function sortEntries(entries) {
     return [...entries].sort((left, right) => {
-        if (left.cacheKind !== right.cacheKind) {
-            return left.cacheKind.localeCompare(right.cacheKind);
-        }
-        return left.entryId.localeCompare(right.entryId);
+        const leftKey = entrySortKey(left);
+        const rightKey = entrySortKey(right);
+        return leftKey < rightKey ? -1 : leftKey > rightKey ? 1 : 0;
     });
 }
 function entrySortKey(entry) {
@@ -329,7 +344,7 @@ function matchesSelector(entry, selector, runtimeInfo) {
     }
     if (selector.version) {
         const version = typeof maybeMeta.version === "string" ? maybeMeta.version : undefined;
-        if (version !== selector.version && !entry.path.includes(selector.version)) {
+        if (version !== selector.version && !pathContainsVersion(entry.path, selector.version)) {
             return false;
         }
     }
@@ -353,17 +368,19 @@ function matchesSelector(entry, selector, runtimeInfo) {
             return false;
         }
     }
-    const normalizedPaths = candidatePathsForEntry(entry)
-        .map((candidate) => normalizePathKey(candidate, runtimeInfo))
-        .filter((candidate) => Boolean(candidate));
-    if (selector.normalizedJarPath && !normalizedPaths.includes(selector.normalizedJarPath)) {
-        return false;
-    }
-    if (selector.normalizedProjectPath) {
-        const projectMatch = normalizedPaths.some((candidate) => candidate === selector.normalizedProjectPath || candidate.startsWith(`${selector.normalizedProjectPath}/`));
-        if (!projectMatch) {
+    if (selector.normalizedJarPath || selector.normalizedProjectPath) {
+        const normalizedPaths = candidatePathsForEntry(entry)
+            .map((candidate) => normalizePathKey(candidate, runtimeInfo))
+            .filter((candidate) => Boolean(candidate));
+        if (selector.normalizedJarPath && !normalizedPaths.includes(selector.normalizedJarPath)) {
             return false;
         }
+        if (selector.normalizedProjectPath) {
+            const projectMatch = normalizedPaths.some((candidate) => candidate === selector.normalizedProjectPath || candidate.startsWith(`${selector.normalizedProjectPath}/`));
+            if (!projectMatch) {
+                return false;
+            }
+        }
     }
     return true;
 }
@@ -441,18 +458,17 @@ function workspaceCacheEntries(workspaceCache) {
         }
     }));
 }
-async function fileBackedEntries(config, cacheKind) {
+async function fileBackedEntries(config, cacheKind, detectCorruption) {
     if (cacheKind === "binary-remap") {
         return binaryRemapEntries(config);
     }
     const root = kindRoot(config, cacheKind);
     const files = await listFilesRecursive(root);
-    const entries = [];
-    for (const filePath of files) {
+    return mapWithConcurrencyLimit(files, CACHE_STAT_CONCURRENCY, async (filePath) => {
         const fileStat = await stat(filePath);
         const normalizedEntryId = filePath.slice(root.length + 1);
         const inferredScope = inferScope(filePath, normalizedEntryId) ?? (cacheKind === "decompiled-source" ? "vanilla" : undefined);
-        entries.push({
+        return {
             cacheKind,
             entryId: normalizedEntryId,
             path: filePath,
@@ -465,7 +481,7 @@ async function fileBackedEntries(config, cacheKind) {
                 scope: inferredScope,
                 projectPath: inferProjectPath(filePath, config.pathRuntimeInfo),
                 partial: fileStat.size === 0,
-                corrupt: cacheKind === "registry" ? isCorruptRegistryJson(filePath) : false,
+                corrupt: cacheKind === "registry" && detectCorruption ? await isCorruptRegistryJson(filePath) : false,
                 inUse: filePath.endsWith(".lock") ||
                     filePath.endsWith(".wal") ||
                     filePath.endsWith(".journal"),
@@ -473,9 +489,8 @@ async function fileBackedEntries(config, cacheKind) {
                     ? { jarPath: filePath }
                     : {})
             }
-        });
-    }
-    return entries;
+        };
+    });
 }
 /**
  * Binary-remap cache entries are keyed by the final artifact id even when the
@@ -556,9 +571,10 @@ async function directoryFileSizeBytes(root) {
 }
 export function createCacheRegistry(config) {
     const workspaceCache = config.workspaceContextCache ?? getProcessWorkspaceContextCache();
-    async function collectEntries(cacheKinds, selector) {
+    async function collectEntries(cacheKinds, selector, detectCorruption = false) {
         const selectedKinds = cacheKinds?.length ? cacheKinds : [...PUBLIC_CACHE_KINDS];
         const preparedSelector = prepareSelector(selector, config.pathRuntimeInfo);
+        const detectCorruptionForKinds = detectCorruption || selector?.status === "corrupt";
         const now = Date.now();
         const entries = await Promise.all(selectedKinds.map((cacheKind) => {
             if (cacheKind === "artifact-index") {
@@ -567,13 +583,15 @@ export function createCacheRegistry(config) {
             if (cacheKind === "workspace") {
                 return Promise.resolve(workspaceCacheEntries(workspaceCache));
             }
-            return fileBackedEntries(config, cacheKind);
+            return fileBackedEntries(config, cacheKind, detectCorruptionForKinds);
         }));
         const enriched = entries
             .flat()
             .map((entry) => ({
             ...entry,
-            status: entry.cacheKind === "workspace" ? entry.status : deriveEntryStatus(entry, config, now)
+            status: entry.cacheKind === "workspace"
+                ? entry.status
+                : deriveEntryStatus(entry, config, now, entry.cacheKind !== "artifact-index")
         }));
         return sortEntries(enriched.filter((entry) => matchesSelector(entry, preparedSelector, config.pathRuntimeInfo)));
     }
@@ -614,7 +632,7 @@ export function createCacheRegistry(config) {
             return entries.slice(0, limit);
         },
         async verifyEntries(input) {
-            const entries = await collectEntries(input.cacheKinds, input.selector);
+            const entries = await collectEntries(input.cacheKinds, input.selector, true);
             const unhealthy = entries.filter((entry) => entry.status !== "healthy");
             const warningStatuses = [...new Set(unhealthy.map((entry) => entry.status))];
             return {

package/dist/config.d.ts

@@ -12,6 +12,7 @@ declare const DEFAULTS: {
     readonly fetchTimeoutMs: 15000;
     readonly fetchRetries: 2;
     readonly searchScanPageSize: 250;
+    readonly searchScanMaxBytes: 67108864;
     readonly indexInsertChunkSize: 200;
     readonly maxMappingGraphCache: 16;
     readonly maxSignatureCache: 2000;

package/dist/config.js

@@ -20,6 +20,7 @@ const DEFAULTS = {
     fetchTimeoutMs: 15000,
     fetchRetries: 2,
     searchScanPageSize: 250,
+    searchScanMaxBytes: 67_108_864,
     indexInsertChunkSize: 200,
     maxMappingGraphCache: 16,
     maxSignatureCache: 2_000,
@@ -41,6 +42,8 @@ const MAX_CACHE_BYTES_LOWER_BOUND = 1_024;
 const TIMEOUT_LOWER_BOUND_MS = 500;
 const SEARCH_SCAN_PAGE_SIZE_LOWER_BOUND = 1;
 const SEARCH_SCAN_PAGE_SIZE_UPPER_BOUND = 10_000;
+const SEARCH_SCAN_MAX_BYTES_LOWER_BOUND = 1_024;
+const SEARCH_SCAN_MAX_BYTES_UPPER_BOUND = 4_294_967_296;
 const INDEX_INSERT_CHUNK_SIZE_LOWER_BOUND = 1;
 const INDEX_INSERT_CHUNK_SIZE_UPPER_BOUND = 20_000;
 const CACHE_ENTRIES_LOWER_BOUND = 1;
@@ -163,6 +166,7 @@ export function loadConfig() {
         fetchTimeoutMs: parseNumber(process.env.MCP_FETCH_TIMEOUT_MS, DEFAULTS.fetchTimeoutMs, TIMEOUT_LOWER_BOUND_MS, Number.MAX_SAFE_INTEGER),
         fetchRetries: parseNumber(process.env.MCP_FETCH_RETRIES, DEFAULTS.fetchRetries, MAX_RETRIES_LOWER_BOUND, MAX_RETRIES_UPPER_BOUND),
         searchScanPageSize: parseNumber(process.env.MCP_SEARCH_SCAN_PAGE_SIZE, DEFAULTS.searchScanPageSize, SEARCH_SCAN_PAGE_SIZE_LOWER_BOUND, SEARCH_SCAN_PAGE_SIZE_UPPER_BOUND),
+        searchScanMaxBytes: parseNumber(process.env.MCP_SEARCH_SCAN_MAX_BYTES, DEFAULTS.searchScanMaxBytes, SEARCH_SCAN_MAX_BYTES_LOWER_BOUND, SEARCH_SCAN_MAX_BYTES_UPPER_BOUND),
         indexInsertChunkSize: parseNumber(process.env.MCP_INDEX_INSERT_CHUNK_SIZE, DEFAULTS.indexInsertChunkSize, INDEX_INSERT_CHUNK_SIZE_LOWER_BOUND, INDEX_INSERT_CHUNK_SIZE_UPPER_BOUND),
         maxMappingGraphCache: parseNumber(process.env.MCP_CACHE_GRAPH_MAX, DEFAULTS.maxMappingGraphCache, CACHE_ENTRIES_LOWER_BOUND, CACHE_ENTRIES_UPPER_BOUND),
         maxSignatureCache: parseNumber(process.env.MCP_CACHE_SIGNATURE_MAX, DEFAULTS.maxSignatureCache, CACHE_ENTRIES_LOWER_BOUND, CACHE_ENTRIES_UPPER_BOUND),

package/dist/decompiler/vineflower.js

@@ -1,4 +1,4 @@
-import { access, constants, mkdir, readFile, readdir, stat } from "node:fs/promises";
+import { access, constants, mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
 import { mkdirSync, rmSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { basename, join, relative, sep } from "node:path";
@@ -8,6 +8,7 @@ import { assertJavaAvailable, runJavaProcess } from "../java-process.js";
 import { log } from "../logger.js";
 const DEFAULT_TIMEOUT_MS = 120_000;
 const DECOMPILED_JAVA_READ_CONCURRENCY = 8;
+const DECOMPILE_COMPLETE_MARKER = ".decompile-complete";
 const VINEFLOWER_FLAG_PROFILES = [
     { label: "default", flags: ["-din=1", "-rbr=1", "-dgs=1"] },
     { label: "relaxed", flags: ["-din=1", "-rbr=0", "-dgs=0"] },
@@ -132,7 +133,10 @@ export async function decompileBinaryJar(binaryJarPath, cacheDir, options) {
     try {
         await mkdir(outputDir, { recursive: true });
         const outputDirStats = await stat(outputDir).catch(() => undefined);
-        if (outputDirStats) {
+        const markerPresent = outputDirStats
+            ? await access(join(outputDir, DECOMPILE_COMPLETE_MARKER), constants.F_OK).then(() => true, () => false)
+            : false;
+        if (outputDirStats && markerPresent) {
             const existingJavaFiles = await collectJavaFiles(outputDir);
             if (existingJavaFiles.length > 0) {
                 const results = await mapWithConcurrencyLimit(existingJavaFiles, DECOMPILED_JAVA_READ_CONCURRENCY, async (candidate) => {
@@ -153,6 +157,7 @@ export async function decompileBinaryJar(binaryJarPath, cacheDir, options) {
                 };
             }
         }
+        clearOutputDir(outputDir);
         await assertVineflowerAvailable(options.vineflowerJarPath);
         await assertJavaAvailable();
         const profilesAttempted = [];
@@ -189,6 +194,7 @@ export async function decompileBinaryJar(binaryJarPath, cacheDir, options) {
                         content: await readFileTreeText(abs)
                     };
                 });
+                await writeFile(join(outputDir, DECOMPILE_COMPLETE_MARKER), profile.label, "utf8");
                 emitDecompileLog("decompile.done", {
                     durationMs: Date.now() - startedAt,
                     artifactIdCandidate: options.artifactIdCandidate,