@adhisang/minecraft-modding-mcp 7.0.0 → 7.1.1

package/dist/entry-tools/validate-project-service.d.ts

@@ -124,9 +124,9 @@ export declare const validateProjectShape: {
     preferProjectVersion: z.ZodOptional<z.ZodBoolean>;
     preferProjectMapping: z.ZodDefault<z.ZodBoolean>;
     detail: z.ZodOptional<z.ZodEnum<{
+        full: "full";
         summary: "summary";
         standard: "standard";
-        full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
         [x: string]: string;
@@ -236,9 +236,9 @@ export declare const validateProjectSchema: z.ZodObject<{
     preferProjectVersion: z.ZodOptional<z.ZodBoolean>;
     preferProjectMapping: z.ZodDefault<z.ZodBoolean>;
     detail: z.ZodOptional<z.ZodEnum<{
+        full: "full";
         summary: "summary";
         standard: "standard";
-        full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
         [x: string]: string;

package/dist/entry-tools/verify-mixin-target-service.js

@@ -51,14 +51,16 @@ function visibilityFromFlags(flags) {
 function buildExampleSnippet(annotation, member, match, mixinMemberName) {
     const accessFlags = match?.accessFlags ?? [];
     const isFinal = accessFlags.includes("final");
+    const isStatic = accessFlags.includes("static");
     const targetName = member.name;
     if (annotation === "@Inject-only") {
-        return `// "${targetName}" is already visible to the mixin (target access: ${accessFlags.filter((f) => f === "public" || f === "protected" || f === "private" || f === "package-private")[0] ?? "unknown"}); use @Inject directly without @Shadow.`;
+        return `// "${targetName}" is already visible to the mixin (target access: ${accessFlags.filter((f) => f === "public" || f === "protected" || f === "private" || f === "package-private")[0] ?? "unknown"}); no @Invoker needed — use @Inject to hook it, or @Shadow to call it from mixin code.`;
     }
     if (annotation === "@Shadow") {
         if (member.kind === "field") {
             const finalTag = isFinal ? "@Shadow @Final\n" : "@Shadow\n";
-            return `${finalTag}private <type> ${targetName};`;
+            const modifiers = isStatic ? "private static" : "private";
+            return `${finalTag}${modifiers} <type> ${targetName};`;
         }
         return `@Shadow\nprivate <returnType> ${targetName}(<params>);`;
     }
@@ -76,9 +78,18 @@ function buildExampleSnippet(annotation, member, match, mixinMemberName) {
 function inferAnnotation(member, match, mixinMemberName) {
     const visibility = match ? deriveVisibility(match.accessFlags) : "private";
     if (visibility === "public" || visibility === "protected") {
+        if (member.kind === "field") {
+            // A visible field needs no @Accessor to be read/written from outside the
+            // mixin, but mixin code still needs @Shadow to reference the field.
+            return {
+                suggestedAnnotation: "@Shadow",
+                reasoning: `Target field "${member.name}" is ${visibility}; no @Accessor is needed to access it from outside, but the mixin still needs @Shadow to reference it.`,
+                exampleSnippet: buildExampleSnippet("@Shadow", member, match, mixinMemberName)
+            };
+        }
         return {
             suggestedAnnotation: "@Inject-only",
-            reasoning: `Target "${member.name}" is ${visibility}; it is already visible to the mixin without @Shadow. Use @Inject directly.`,
+            reasoning: `Target method "${member.name}" is ${visibility}; it is already visible to the mixin, so no @Invoker is needed. Use @Inject to hook it, or @Shadow to call it from mixin code.`,
             exampleSnippet: buildExampleSnippet("@Inject-only", member, match, mixinMemberName)
         };
     }
@@ -99,30 +110,30 @@ function inferAnnotation(member, match, mixinMemberName) {
         }
         return {
             suggestedAnnotation: "@Shadow",
-            reasoning: `Target "${member.name}" is private. mixin member "${mixinMemberName}" does not match accessor/invoker prefix conventions; @Shadow is appropriate.`,
+            reasoning: `Target "${member.name}" is ${visibility}. mixin member "${mixinMemberName}" does not match accessor/invoker prefix conventions; @Shadow is appropriate.`,
             exampleSnippet: buildExampleSnippet("@Shadow", member, match, mixinMemberName)
         };
     }
     if (member.kind === "field") {
         return {
             suggestedAnnotation: "@Shadow",
-            reasoning: `Target "${member.name}" is private; use @Shadow to access it from the mixin.`,
+            reasoning: `Target "${member.name}" is ${visibility}; use @Shadow to access it from the mixin.`,
             exampleSnippet: buildExampleSnippet("@Shadow", member, match, mixinMemberName)
         };
     }
     return {
         suggestedAnnotation: null,
-        reasoning: `Target method "${member.name}" is private and no mixinMemberName was supplied; cannot decide between @Shadow and @Invoker. Choose @Shadow when the mixin overrides the method, @Invoker when it only needs to call it.`,
+        reasoning: `Target method "${member.name}" is ${visibility} and no mixinMemberName was supplied; cannot decide between @Shadow and @Invoker. Choose @Shadow when the mixin overrides the method, @Invoker when it only needs to call it.`,
         exampleSnippet: "// Provide mixinMemberName to receive a concrete @Shadow or @Invoker template.",
         candidates: [
             {
                 annotation: "@Shadow",
-                reasoning: "Use @Shadow to override or read the private method body from the mixin.",
+                reasoning: `Use @Shadow to override or read the ${visibility} method body from the mixin.`,
                 exampleSnippet: buildExampleSnippet("@Shadow", member, match, mixinMemberName)
             },
             {
                 annotation: "@Invoker",
-                reasoning: "Use @Invoker when the mixin only needs to invoke the private method without redeclaring the body.",
+                reasoning: `Use @Invoker when the mixin only needs to invoke the ${visibility} method without redeclaring the body.`,
                 exampleSnippet: buildExampleSnippet("@Invoker", member, match, mixinMemberName)
             }
         ]

package/dist/index.js

@@ -11,6 +11,7 @@ import { prepareToolInput } from "./tool-input.js";
 import { DETAIL_ENABLED_TOOL_NAMES, DEFAULT_DETAIL_BY_TOOL, projectByDetail } from "./response-utils.js";
 import { loadConfig } from "./config.js";
 import { createError, ERROR_CODES, isAppError } from "./errors.js";
+import { convertRuntimeSqliteCorruption } from "./storage/db.js";
 import { log } from "./logger.js";
 import { applyNbtJsonPatch, nbtBase64ToTypedJson, typedJsonToNbtBase64 } from "./nbt/pipeline.js";
 import { analyzeModJar } from "./mod-analyzer.js";
@@ -136,7 +137,8 @@ const analyzeSymbolService = new AnalyzeSymbolService({
 const compareMinecraftService = new CompareMinecraftService({
     compareVersions: (input) => sourceService.compareVersions(input),
     diffClassSignatures: (input) => sourceService.diffClassSignatures(input),
-    getRegistryData: (input) => sourceService.getRegistryData(input)
+    getRegistryData: (input) => sourceService.getRegistryData(input),
+    getVersionLibraries: (input) => sourceService.getVersionLibraries(input.version)
 });
 const analyzeModService = new AnalyzeModService({
     analyzeModJar: (jarPath, options) => analyzeModJar(jarPath, options),
@@ -428,38 +430,58 @@ async function runTool(tool, rawInput, schema, action) {
         });
     }
     catch (caughtError) {
-        const problem = mapErrorToProblem(caughtError, requestId, {
+        // A raw SQLite corruption error surfaced mid-call (as opposed to at DB
+        // open, which is already a typed AppError by the time it gets here) means
+        // quick_check passed for this file but a live query still hit corruption.
+        // Escalate the next open to a full integrity_check and report a typed,
+        // restart-guiding ERR_DB_FAILURE instead of leaking ERR_INTERNAL.
+        const reportedError = convertRuntimeSqliteCorruption(caughtError, config.sqlitePath);
+        if (reportedError !== caughtError) {
+            // The public envelope only ever gets the generic ERR_DB_FAILURE message
+            // and nextAction (see convertRuntimeSqliteCorruption) - the original
+            // SQLite diagnostic is server-side-only, logged here with the request
+            // context convertRuntimeSqliteCorruption itself does not have access to.
+            const rawSqliteError = caughtError;
+            log("error", "tool.call.sqlite_runtime_corruption", {
+                requestId,
+                tool,
+                message: typeof rawSqliteError?.message === "string" ? rawSqliteError.message : String(caughtError),
+                code: rawSqliteError?.code,
+                errcode: rawSqliteError?.errcode
+            });
+        }
+        const problem = mapErrorToProblem(reportedError, requestId, {
             tool,
             normalizedInput
         });
-        if (isAppError(caughtError)) {
-            const isSevere = caughtError.code === ERROR_CODES.DB_FAILURE ||
-                caughtError.code === ERROR_CODES.REPO_FETCH_FAILED ||
-                caughtError.code === ERROR_CODES.REGISTRY_GENERATION_FAILED ||
-                caughtError.code === ERROR_CODES.JAVA_UNAVAILABLE ||
-                caughtError.code.startsWith("ERR_DECOMPILER");
+        if (isAppError(reportedError)) {
+            const isSevere = reportedError.code === ERROR_CODES.DB_FAILURE ||
+                reportedError.code === ERROR_CODES.REPO_FETCH_FAILED ||
+                reportedError.code === ERROR_CODES.REGISTRY_GENERATION_FAILED ||
+                reportedError.code === ERROR_CODES.JAVA_UNAVAILABLE ||
+                reportedError.code.startsWith("ERR_DECOMPILER");
             if (isSevere) {
                 log("error", "tool.call.failed", {
                     requestId,
                     tool,
-                    code: caughtError.code,
-                    message: caughtError.message
+                    code: reportedError.code,
+                    message: reportedError.message
                 });
             }
             else {
                 log("warn", "tool.call.warning", {
                     requestId,
                     tool,
-                    code: caughtError.code,
-                    message: caughtError.message
+                    code: reportedError.code,
+                    message: reportedError.message
                 });
             }
         }
-        else if (!(caughtError instanceof ZodError)) {
+        else if (!(reportedError instanceof ZodError)) {
             log("error", "tool.call.unhandled", {
                 requestId,
                 tool,
-                reason: caughtError instanceof Error ? caughtError.message : String(caughtError)
+                reason: reportedError instanceof Error ? reportedError.message : String(reportedError)
             });
         }
         const errorDurationMs = Date.now() - startedAt;
@@ -469,7 +491,7 @@ async function runTool(tool, rawInput, schema, action) {
             tool,
             durationMs: errorDurationMs
         };
-        applyErrorMetaExtensions(errorMeta, caughtError);
+        applyErrorMetaExtensions(errorMeta, reportedError);
         return objectResult({
             error: problem,
             meta: errorMeta
@@ -688,6 +710,7 @@ function buildServer(ctx) {
             access: input.access,
             includeSynthetic: input.includeSynthetic,
             includeInherited: input.includeInherited,
+            includeAnnotations: input.includeAnnotations,
             memberPattern: input.memberPattern,
             maxMembers: input.maxMembers,
             projection: input.projection,

package/dist/java-process.d.ts

@@ -1,5 +1,6 @@
 import { spawn } from "node:child_process";
 export declare const MAX_STDIO_SNAPSHOT = 6240;
+export declare const JAVA_PROCESS_KILL_GRACE_MS = 3000;
 export interface JavaProcessOptions {
     jarPath: string;
     args: string[];

package/dist/java-process.js

@@ -3,6 +3,11 @@ import { createError, ERROR_CODES } from "./errors.js";
 import { normalizePathForHost } from "./path-converter.js";
 const JAVA_CHECK_TIMEOUT_MS = 2_000;
 export const MAX_STDIO_SNAPSHOT = 6_240;
+// How long to wait after SIGTERM before escalating to SIGKILL on a timed-out
+// Java process. This is a single leaf process (not a process tree — the
+// supervisor's tree-termination path is a separate concern), so a direct
+// SIGKILL here is the sanctioned escalation, not a workaround.
+export const JAVA_PROCESS_KILL_GRACE_MS = 3_000;
 let javaAvailabilitySpawn = spawn;
 let javaAvailabilityPromise;
 export function limitStdio(text) {
@@ -95,8 +100,15 @@ export function runJavaProcess(options) {
         });
         let stdout = "";
         let stderr = "";
+        let killTimer;
         const timer = setTimeout(() => {
             proc.kill();
+            killTimer = setTimeout(() => {
+                // The process ignored SIGTERM past the grace period; escalate to
+                // SIGKILL so a hung JVM cannot outlive the timeout indefinitely.
+                proc.kill("SIGKILL");
+            }, JAVA_PROCESS_KILL_GRACE_MS);
+            killTimer.unref();
             reject(createError({
                 code: ERROR_CODES.JAVA_PROCESS_FAILED,
                 message: "Java process timed out.",
@@ -118,6 +130,7 @@ export function runJavaProcess(options) {
         });
         proc.once("error", (error) => {
             clearTimeout(timer);
+            clearTimeout(killTimer);
             reject(createError({
                 code: ERROR_CODES.JAVA_PROCESS_FAILED,
                 message: "Java process failed to start.",
@@ -129,6 +142,7 @@ export function runJavaProcess(options) {
         });
         proc.once("close", (code) => {
             clearTimeout(timer);
+            clearTimeout(killTimer);
             resolve({
                 exitCode: code ?? -1,
                 stdoutTail: limitStdio(stdout),

package/dist/mapping/lookup.js

@@ -55,6 +55,15 @@ export function lookupCandidates(index, query) {
         addCandidates(collected, index, index.simple.get(key), "simple-name", 0.75);
     }
     return [...collected.values()]
+        // A lookup answers only with candidates of the query's own kind. The index buckets
+        // deliberately mix kinds: `exactLookupKeys` registers every method a second time
+        // under the descriptorless `owner.name` key that a FIELD's symbol also uses, and
+        // `simpleLookupKeys` files classes, fields and methods under the same bare name. So
+        // a field query could be answered with a same-named method's target name at
+        // exact/confidence 1, or with a class that merely shares its simple name. Filtering
+        // here — before the MAX_CANDIDATES slice — also keeps wrong-kind rows from crowding
+        // the right one out of a busy name's bucket.
+        .filter((candidate) => candidate.record.kind === query.kind)
         .sort((left, right) => {
         if (right.confidence !== left.confidence) {
             return right.confidence - left.confidence;
@@ -415,14 +424,20 @@ export function projectLookupCandidateDescriptor(candidate, sourceDescriptor, ta
     // namespace. Multi-hop paths that already produced a target-side descriptor are left
     // unchanged by design.
     if (candidate.kind !== "method" ||
+        !candidate.owner ||
         !candidate.descriptor ||
         !targetDescriptor ||
         candidate.descriptor !== sourceDescriptor) {
         return candidate;
     }
+    // `symbol` embeds the descriptor, so replacing only the `descriptor` field left the
+    // SOURCE-namespace descriptor inside an otherwise target-namespace symbol — one
+    // SymbolReference advertising two namespaces at once. Rebuild it from the target
+    // owner + name + descriptor with the same helper the parsers use.
     return {
         ...candidate,
-        descriptor: targetDescriptor
+        descriptor: targetDescriptor,
+        symbol: createMethodSymbolRecord(candidate.owner, candidate.name, targetDescriptor).symbol
     };
 }
 export function effectiveLoomSearchProjectPath(projectPath) {

package/dist/mapping-service.d.ts

@@ -56,6 +56,20 @@ export declare class MappingService {
      * accepted alias so an owner that the mapping does not rename still matches itself.
      */
     private acceptedOwnersAlongPath;
+    /**
+     * The descriptor forms a stored record may legitimately carry for a query written
+     * in `sourceMapping` coordinates: the caller's own descriptor, the target-space
+     * projection, and the projection into each base namespace.
+     *
+     * Tiny v2 writes one descriptor per method row, in the file's FIRST namespace, and
+     * shares it across every column. A merged Loom rendering puts that in obfuscated
+     * coordinates, but a workspace whose `official intermediary` and `intermediary named`
+     * mappings are SEPARATE files leaves the last hop's record carrying an
+     * intermediary-coordinate descriptor, which an obfuscated-only accepted set rejected
+     * as `not_found`. Projecting along every reachable base namespace is the same rule
+     * `checkSymbolExists` applies.
+     */
+    private acceptedDescriptorForms;
     private projectMethodDescriptorToTarget;
     private provenanceForPath;
     /**

package/dist/mapping-service.js

@@ -193,15 +193,10 @@ export class MappingService {
             // only against the fully projected target descriptor dropped those valid candidates
             // and produced false `not_found` for common Mojang -> Yarn lookups. Accept any
             // candidate whose descriptor matches the caller's descriptor, the target-space
-            // projection, or the obfuscated-space projection — the three forms that actually
-            // appear in the mapping graph.
+            // projection, or a base-namespace projection — the forms that actually appear in
+            // the mapping graph.
             const strictDescriptor = projectedDescriptor ?? queryRecord.descriptor;
-            const acceptedDescriptors = new Set([queryRecord.descriptor, strictDescriptor]);
-            const toObfuscatedPath = namespacePath(graph, sourceMapping, "obfuscated");
-            if (toObfuscatedPath) {
-                const obfuscatedProjection = this.projectMethodDescriptorToTarget(graph, toObfuscatedPath, queryRecord.descriptor);
-                acceptedDescriptors.add(obfuscatedProjection.descriptor);
-            }
+            const acceptedDescriptors = this.acceptedDescriptorForms(graph, sourceMapping, queryRecord.descriptor, strictDescriptor);
             rawCandidates = rawCandidates.filter((candidate) => candidate.descriptor !== undefined && acceptedDescriptors.has(candidate.descriptor));
         }
         const disambiguatedCandidates = applyDisambiguationHints(rawCandidates, input.disambiguation, warnings);
@@ -402,12 +397,7 @@ export class MappingService {
         const candidates = rawCandidates.map(toResolutionCandidate);
         const limitedCandidates = limitResolutionCandidates(candidates, input.maxCandidates);
         const strictDescriptor = projectedDescriptor ?? descriptor;
-        const acceptedDescriptors = new Set([descriptor, strictDescriptor]);
-        const toObfuscatedPath = namespacePath(graph, sourceMapping, "obfuscated");
-        if (toObfuscatedPath) {
-            const obfuscatedProjection = this.projectMethodDescriptorToTarget(graph, toObfuscatedPath, descriptor);
-            acceptedDescriptors.add(obfuscatedProjection.descriptor);
-        }
+        const acceptedDescriptors = this.acceptedDescriptorForms(graph, sourceMapping, descriptor, strictDescriptor);
         // "Strict" is the query's full advertised triple: owner + name + descriptor. The
         // descriptor alone is not enough, because `lookupCandidates` also indexes methods
         // under the OWNERLESS `<name><descriptor>` simple-name key — so a same-signature
@@ -1069,6 +1059,33 @@ export class MappingService {
         }
         return accepted;
     }
+    /**
+     * The descriptor forms a stored record may legitimately carry for a query written
+     * in `sourceMapping` coordinates: the caller's own descriptor, the target-space
+     * projection, and the projection into each base namespace.
+     *
+     * Tiny v2 writes one descriptor per method row, in the file's FIRST namespace, and
+     * shares it across every column. A merged Loom rendering puts that in obfuscated
+     * coordinates, but a workspace whose `official intermediary` and `intermediary named`
+     * mappings are SEPARATE files leaves the last hop's record carrying an
+     * intermediary-coordinate descriptor, which an obfuscated-only accepted set rejected
+     * as `not_found`. Projecting along every reachable base namespace is the same rule
+     * `checkSymbolExists` applies.
+     */
+    acceptedDescriptorForms(graph, sourceMapping, descriptor, targetDescriptor) {
+        const accepted = new Set([descriptor, targetDescriptor]);
+        for (const baseNamespace of ["obfuscated", "intermediary"]) {
+            if (sourceMapping === baseNamespace) {
+                continue;
+            }
+            const projectionPath = namespacePath(graph, sourceMapping, baseNamespace);
+            if (!projectionPath) {
+                continue;
+            }
+            accepted.add(this.projectMethodDescriptorToTarget(graph, projectionPath, descriptor).descriptor);
+        }
+        return accepted;
+    }
     projectMethodDescriptorToTarget(graph, path, descriptor) {
         let hadClassReferences = false;
         let complete = true;
@@ -1156,7 +1173,10 @@ export class MappingService {
             return {
                 mojangMappingsAvailable: false,
                 tinyMappingsAvailable: !needsTinyMappings,
-                memberRemapAvailable: false,
+                // Obfuscated requests never need a remap path (the target is already
+                // obfuscated), same as the loaded-graph branch below — a failed graph
+                // load does not degrade an obfuscated request's remap availability.
+                memberRemapAvailable: input.requestedMapping === "obfuscated",
                 degradations: ["Mapping graph could not be loaded."]
             };
         }

package/dist/minecraft-explorer-service.js

@@ -1,5 +1,5 @@
 import { realpathSync } from "node:fs";
-import { createError, ERROR_CODES } from "./errors.js";
+import { createError, ERROR_CODES, isAppError } from "./errors.js";
 import { loadConfig } from "./config.js";
 import { normalizeJarPath, readJarStatStamp } from "./path-resolver.js";
 import { createJarEntryReader } from "./source-jar-reader.js";
@@ -447,22 +447,44 @@ class ByteReader {
     constructor(buffer) {
         this.buffer = buffer;
     }
+    // Mirrors NbtReader's ensure() (src/nbt/java-nbt-codec.ts). Without this,
+    // Buffer.subarray silently clips a length past EOF instead of throwing, so
+    // a truncated attribute body (declared length intact, trailing bytes
+    // missing) reads as a shorter-than-declared Buffer and the offset still
+    // advances past the true end - readBytes "succeeds" on corrupted data.
+    ensure(length) {
+        if (this.offset + length > this.buffer.length) {
+            throw createError({
+                code: ERROR_CODES.INTERNAL,
+                message: "Unexpected end of class file data. Class file may be corrupted.",
+                details: {
+                    offset: this.offset,
+                    requiredBytes: length,
+                    remainingBytes: this.buffer.length - this.offset
+                }
+            });
+        }
+    }
     readU1() {
+        this.ensure(1);
         const value = this.buffer.readUInt8(this.offset);
         this.offset += 1;
         return value;
     }
     readU2() {
+        this.ensure(2);
         const value = this.buffer.readUInt16BE(this.offset);
         this.offset += 2;
         return value;
     }
     readU4() {
+        this.ensure(4);
         const value = this.buffer.readUInt32BE(this.offset);
         this.offset += 4;
         return value;
     }
     readBytes(length) {
+        this.ensure(length);
         const slice = this.buffer.subarray(this.offset, this.offset + length);
         this.offset += length;
         return slice;
@@ -773,7 +795,26 @@ export class MinecraftExplorerService {
                     details: { fqn, jarPath, classEntryPath }
                 });
             }
-            parsed = parseClassFile(classBuffer);
+            try {
+                parsed = parseClassFile(classBuffer);
+            }
+            catch (error) {
+                // A primary-class parse failure of ANY origin - a raw Buffer bounds
+                // error (ByteReader has no bounds checks), or one of parseClassFile's
+                // own deliberate throws (bad magic, unsupported constant-pool tag) -
+                // is third-party jar content, never blamed on the caller as
+                // ERR_INTERNAL. An AppError that already carries ERR_CLASS_NOT_FOUND
+                // (readUtf8/readClassName) is already in the right shape and passes
+                // through unchanged.
+                if (isAppError(error) && error.code === ERROR_CODES.CLASS_NOT_FOUND) {
+                    throw error;
+                }
+                throw createError({
+                    code: ERROR_CODES.CLASS_NOT_FOUND,
+                    message: `Class "${fqn}" in "${jarPath}" is malformed or truncated. Class file may be corrupted.`,
+                    details: { fqn, jarPath, classEntryPath }
+                });
+            }
         }
         catch (error) {
             reader.close();
@@ -863,12 +904,23 @@ export class MinecraftExplorerService {
         reader.close();
         const toSignatureMember = (ownerFqn, ownerSimpleClassName, member, category) => {
             if (category === "field") {
-                const parsedField = parseFieldType(member.descriptor, 0, { allowVoid: false });
-                if (parsedField.next !== member.descriptor.length) {
+                // parseFieldType/parseMethodDescriptor throw ERR_INVALID_INPUT, which
+                // blames the caller; a member descriptor comes from third-party
+                // bytecode, not tool input, so a malformed one is treated like the
+                // corrupted-class failure above (src/source/descriptor-utils.ts
+                // degrades the same parsers rather than throwing at all).
+                let parsedField;
+                try {
+                    parsedField = parseFieldType(member.descriptor, 0, { allowVoid: false });
+                    if (parsedField.next !== member.descriptor.length) {
+                        throw new Error("Trailing bytes after field descriptor.");
+                    }
+                }
+                catch {
                     throw createError({
-                        code: ERROR_CODES.INVALID_INPUT,
-                        message: `Invalid field descriptor "${member.descriptor}".`,
-                        details: { descriptor: member.descriptor, position: parsedField.next }
+                        code: ERROR_CODES.CLASS_NOT_FOUND,
+                        message: `Field "${member.name}" in "${ownerFqn}" has a malformed descriptor in "${jarPath}". Class file may be corrupted.`,
+                        details: { ownerFqn, jarPath, member: member.name, descriptor: member.descriptor }
                     });
                 }
                 const fieldType = parsedField.type;
@@ -884,7 +936,17 @@ export class MinecraftExplorerService {
                     ...(member.annotations ? { annotations: member.annotations } : {})
                 };
             }
-            const parsedMethod = parseMethodDescriptor(member.descriptor);
+            let parsedMethod;
+            try {
+                parsedMethod = parseMethodDescriptor(member.descriptor);
+            }
+            catch {
+                throw createError({
+                    code: ERROR_CODES.CLASS_NOT_FOUND,
+                    message: `Method "${member.name}" in "${ownerFqn}" has a malformed descriptor in "${jarPath}". Class file may be corrupted.`,
+                    details: { ownerFqn, jarPath, member: member.name, descriptor: member.descriptor }
+                });
+            }
             const modifiers = modifierPrefix(member.accessFlags, "method");
             const args = parsedMethod.args.join(", ");
             if (member.name === "<init>") {

package/dist/mixin/access-validators.js

@@ -1,10 +1,46 @@
 import { accessLevelFromFlags, allFieldNames, allMethodNames, suggestSimilar } from "./helpers.js";
+const VALID_AW_HEADER_VERSIONS = new Set(["v1", "v2"]);
+/**
+ * Fabric access widener grammar rules (AUTHORITY): `accessible` applies to
+ * class, method, field; `extendable` applies to class and method only;
+ * `mutable` applies to field only; `transitive-` exists only under a v2
+ * header. Returns a line+rule message when `entry` breaks one of these, or
+ * undefined when the pairing is legal.
+ */
+function checkAccessWidenerEntryLegality(entry, headerVersion) {
+    if (entry.kind === "mutable" && entry.targetKind !== "field") {
+        return `Line ${entry.line}: "mutable" only applies to field, not ${entry.targetKind}.`;
+    }
+    if (entry.kind === "extendable" && entry.targetKind === "field") {
+        return `Line ${entry.line}: "extendable" does not apply to field (only class and method).`;
+    }
+    if (entry.transitive && headerVersion !== "v2") {
+        return `Line ${entry.line}: "transitive-" entries require a v2 header (declared "${headerVersion || "none"}").`;
+    }
+    return undefined;
+}
 export function validateParsedAccessWidener(parsed, membersByClass, warnings, options) {
     warnings.push(...parsed.parseWarnings);
+    let headerValid = true;
+    const headerLine = parsed.headerLine ?? 1;
+    if (!parsed.headerVersion) {
+        headerValid = false;
+        warnings.push(`Line ${headerLine}: accessWidener requires a header line ("accessWidener <v1|v2> <namespace>"); none was found.`);
+    }
+    else if (!VALID_AW_HEADER_VERSIONS.has(parsed.headerVersion)) {
+        headerValid = false;
+        warnings.push(`Line ${headerLine}: Unsupported accessWidener header version "${parsed.headerVersion}" (expected v1 or v2).`);
+    }
     const validatedEntries = [];
     let validCount = 0;
     let invalidCount = 0;
     for (const entry of parsed.entries) {
+        const legalityIssue = checkAccessWidenerEntryLegality(entry, parsed.headerVersion);
+        if (legalityIssue) {
+            validatedEntries.push({ ...entry, valid: false, issue: legalityIssue });
+            invalidCount++;
+            continue;
+        }
         const ownerFqn = entry.target.replace(/\//g, ".");
         if (entry.targetKind === "class") {
             const members = membersByClass.get(ownerFqn);
@@ -130,7 +166,7 @@ export function validateParsedAccessWidener(parsed, membersByClass, warnings, op
     return {
         headerVersion: parsed.headerVersion,
         namespace: parsed.namespace,
-        valid: invalidCount === 0,
+        valid: invalidCount === 0 && headerValid && (parsed.rejectedEntryCount ?? 0) === 0,
         entries: validatedEntries,
         summary: {
             total: parsed.entries.length,
@@ -276,7 +312,7 @@ export function validateParsedAccessTransformer(parsed, membersByClass, warnings
         validCount++;
     }
     return {
-        valid: invalidCount === 0,
+        valid: invalidCount === 0 && (parsed.rejectedEntryCount ?? 0) === 0,
         entries: validatedEntries,
         summary: {
             total: parsed.entries.length,