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

package/dist/entry-tools/validate-project/cases/project-summary.js

@@ -15,6 +15,40 @@ async function safeEmit(emitter, stage, payload) {
         // swallow telemetry failure
     }
 }
+const DISCOVER_KIND_LABELS = [
+    ["mixins", "mixin configs"],
+    ["access-wideners", "access wideners"],
+    ["access-transformers", "access transformers"]
+];
+function joinWithOr(items) {
+    if (items.length <= 2) {
+        return items.join(" or ");
+    }
+    return `${items.slice(0, -1).join(", ")}, or ${items[items.length - 1]}`;
+}
+// A run that discovered no files keeps status "ok" (nothing failed), so the
+// headline and a warning must say that nothing was checked; otherwise the
+// result reads as a pass. Only the kinds subject.discover searched are named.
+function describeNothingToValidate(discover, projectPath) {
+    const searched = DISCOVER_KIND_LABELS
+        .filter(([kind]) => discover.includes(kind))
+        .map(([, label]) => label);
+    const notOk = "so status \"ok\" does not mean any file passed validation.";
+    const accessTransformerHint = discover.includes("access-transformers")
+        ? ""
+        : " Access Transformer files are searched only when subject.discover includes \"access-transformers\".";
+    if (searched.length === 0) {
+        return {
+            headline: "Nothing to validate: subject.discover selected no file kinds to search.",
+            warning: `Nothing was validated: subject.discover selected no file kinds to search, ${notOk}${accessTransformerHint}`
+        };
+    }
+    const list = joinWithOr(searched);
+    return {
+        headline: `Nothing to validate: no ${list} were found.`,
+        warning: `Nothing was validated: no ${list} were found under ${projectPath}, ${notOk}${accessTransformerHint}`
+    };
+}
 export async function handleProjectSummary(deps, input, detail, include, options = {}) {
     // Forwarded emitter for nested validators and probes; same swallow contract
     // as safeEmit so a rejecting raw emitter cannot leak into their outcomes.
@@ -27,7 +61,9 @@ export async function handleProjectSummary(deps, input, detail, include, options
             message: "task=project-summary requires subject.kind=workspace."
         });
     }
-    if (!input.version && !input.preferProjectVersion) {
+    // An omitted version is inferred from the project below; only an explicit
+    // preferProjectVersion=false opts out of that inference.
+    if (!input.version && input.preferProjectVersion === false) {
         const baseResult = buildEntryToolResult({
             task: "project-summary",
             detail,
@@ -52,7 +88,7 @@ export async function handleProjectSummary(deps, input, detail, include, options
                     }
                 ],
                 notes: [
-                    "Pass version explicitly, or retry with preferProjectVersion=true when gradle.properties declares the Minecraft version. The suggested retry sets preferProjectVersion=true for you."
+                    "Version inference was suppressed by preferProjectVersion=false. Pass version explicitly, or retry without preferProjectVersion=false to infer it from gradle.properties. The suggested retry sets preferProjectVersion=true for you."
                 ]
             },
             blocks: {
@@ -79,10 +115,21 @@ export async function handleProjectSummary(deps, input, detail, include, options
         projectPath,
         discover
     });
-    const detectedProjectVersion = input.preferProjectVersion
+    // preferProjectVersion=true overrides an explicit version; an omitted version is
+    // inferred (the explicit-false opt-out returned above).
+    const detectedProjectVersion = input.preferProjectVersion === true || !input.version
         ? await deps.detectProjectMinecraftVersion?.(projectPath)
         : undefined;
     const resolvedVersion = detectedProjectVersion ?? input.version;
+    const versionInferred = !input.version && Boolean(detectedProjectVersion);
+    // An inferred version is a project-version resolution: sub-validators and the
+    // artifact probe see exactly what an explicit preferProjectVersion=true run sees.
+    const effectivePreferProjectVersion = versionInferred ? true : input.preferProjectVersion;
+    const versionInferenceWarnings = versionInferred
+        ? [
+            `version was inferred from the workspace: ${detectedProjectVersion} (source: projectPath:gradle.properties (${projectPath})).`
+        ]
+        : [];
     const [mixinConfigs, accessWideners, accessTransformers] = await Promise.all([
         discover.includes("mixins")
             ? deps.discoverMixins(projectPath, input.configPaths)
@@ -111,17 +158,20 @@ export async function handleProjectSummary(deps, input, detail, include, options
                     sourcePriority: input.sourcePriority,
                     scope: input.scope
                 }),
+                // Retrying without a version would infer, fail, and block again, so the
+                // recovery asks for an explicit version instead.
                 nextActions: [
                     {
                         tool: "validate-project",
                         params: {
                             task: "project-summary",
-                            subject: input.subject
+                            subject: input.subject,
+                            version: "<minecraft-version>"
                         }
                     }
                 ],
                 notes: [
-                    "Pass version explicitly, or make sure gradle.properties declares the Minecraft version before using preferProjectVersion=true."
+                    "The Minecraft version could not be inferred from gradle.properties (minecraft_version, mc_version, or minecraftVersion). Retry with version set explicitly: replace \"<minecraft-version>\" in the suggested call with the project's Minecraft version, or declare it in gradle.properties."
                 ]
             },
             blocks: {
@@ -150,14 +200,16 @@ export async function handleProjectSummary(deps, input, detail, include, options
             ]
         };
     }
+    // Reached only when discovery found nothing (the branch above handles found files).
     if (!resolvedVersion) {
+        const nothingToValidate = describeNothingToValidate(discover, projectPath);
         const baseResult = buildEntryToolResult({
             task: "project-summary",
             detail,
             include,
             summary: {
                 status: "ok",
-                headline: `Validated ${mixinConfigs.length} mixin config(s), ${accessWideners.length} access widener(s), and ${accessTransformers.length} access transformer(s).`,
+                headline: nothingToValidate.headline,
                 subject: createSummarySubject({
                     task: "project-summary",
                     kind: input.subject.kind,
@@ -187,11 +239,11 @@ export async function handleProjectSummary(deps, input, detail, include, options
         return {
             ...baseResult,
             ...(tasks ? { tasks } : {}),
-            warnings: []
+            warnings: [nothingToValidate.warning]
         };
     }
     const validationVersion = resolvedVersion;
-    const warnings = [];
+    const warnings = [...versionInferenceWarnings];
     const mixinDurationStart = Date.now();
     let validMixins = 0;
     let partialMixins = 0;
@@ -288,7 +340,7 @@ export async function handleProjectSummary(deps, input, detail, include, options
                 projectPath,
                 gradleUserHome,
                 scope: input.scope,
-                preferProjectVersion: input.preferProjectVersion
+                preferProjectVersion: effectivePreferProjectVersion
             });
             if (output.valid) {
                 validAw += 1;
@@ -337,7 +389,7 @@ export async function handleProjectSummary(deps, input, detail, include, options
                 projectPath,
                 gradleUserHome,
                 scope: input.scope,
-                preferProjectVersion: input.preferProjectVersion
+                preferProjectVersion: effectivePreferProjectVersion
             });
             if (output.valid) {
                 validAt += 1;
@@ -361,13 +413,20 @@ export async function handleProjectSummary(deps, input, detail, include, options
     const invalidCount = invalidMixins + invalidAw + invalidAt;
     const partialCount = partialMixins;
     const status = invalidCount > 0 ? "invalid" : partialCount > 0 ? "partial" : "ok";
+    const nothingToValidate = mixinConfigs.length === 0 && accessWideners.length === 0 && accessTransformers.length === 0
+        ? describeNothingToValidate(discover, projectPath)
+        : undefined;
+    if (nothingToValidate) {
+        warnings.push(nothingToValidate.warning);
+    }
     const baseResult = buildEntryToolResult({
         task: "project-summary",
         detail,
         include,
         summary: {
             status,
-            headline: `Validated ${mixinConfigs.length} mixin config(s), ${accessWideners.length} access widener(s), and ${accessTransformers.length} access transformer(s).`,
+            headline: nothingToValidate?.headline ??
+                `Validated ${mixinConfigs.length} mixin config(s), ${accessWideners.length} access widener(s), and ${accessTransformers.length} access transformer(s).`,
             subject: createSummarySubject({
                 task: "project-summary",
                 kind: input.subject.kind,
@@ -416,7 +475,7 @@ export async function handleProjectSummary(deps, input, detail, include, options
         sourcePriority: input.sourcePriority,
         gradleUserHome,
         scope: input.scope,
-        preferProjectVersion: input.preferProjectVersion,
+        preferProjectVersion: effectivePreferProjectVersion,
         mixinDiscoveryCount: mixinConfigs.length,
         mixinCaughtErrors,
         mixinCounts: { ok: validMixins, partial: partialMixins, invalid: invalidMixins },

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/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

package/dist/json-rpc-framing.d.ts

@@ -78,6 +78,15 @@ export declare class JsonRpcFrameReader {
     private awaitedBodyStart;
     private idleTimer;
     private fatal;
+    /**
+     * Set when an oversized, not-yet-terminated line/header-less run was just
+     * discarded with no newline in hand. The bytes that eventually complete
+     * that same logical line are not a delimiter the reader can trust as the
+     * start of a fresh frame, so every byte up to and including the next 0x0a —
+     * however many chunks it takes to arrive — is swallowed unread before
+     * normal parsing resumes. See `rejectOversizedIncompleteInput`.
+     */
+    private discardingOversizedLine;
     /**
      * @param options.maxFrameBytes Largest accepted frame; defaults to
      *   {@link loadMaxFrameBytes}.
@@ -128,6 +137,17 @@ export declare class JsonRpcFrameReader {
      * a caller that does not still gets a live pair rather than a stale one.
      */
     private armIdleTimer;
+    /**
+     * Whether the buffer, despite `mode` still sticking at "content-length"
+     * from an earlier frame, actually opens a line-mode frame — the same probe
+     * `readContentLengthMessage` uses to detect the mid-stream switch back to
+     * line framing (a JSON object/array opener can never begin a Content-Length
+     * header block). Used to keep the header-size ceiling scoped to buffers
+     * still being accumulated as a header block, so it never judges a line
+     * frame's bytes as an oversized header just because the switch hasn't been
+     * recognized yet.
+     */
+    private looksLikeLineFrame;
     private canCompleteFrame;
     private rejectOversizedIncompleteInput;
     /**

package/dist/json-rpc-framing.js

@@ -40,8 +40,10 @@ const clearIdleTimerHandle = (handle) => {
  *
  * Consequence worth stating, because it is load-bearing for the caller: an
  * EXTRA empty line after the terminator is body, not header. The body window
- * then opens on that empty line and is shifted by the two or three bytes the
- * peer did not count, so it no longer covers the same span as the JSON value.
+ * then opens on that empty line, shifted by however many bytes that line's own
+ * terminator took — one for a bare LF, two for CRLF — bytes the peer's
+ * declared length did not count, so the window no longer covers the same span
+ * as the JSON value.
  * All four extra-blank-line shapes behave alike here, which is the point: the
  * reading does not depend on which terminator style the peer chose.
  *
@@ -171,6 +173,15 @@ export class JsonRpcFrameReader {
     awaitedBodyStart = -1;
     idleTimer;
     fatal = false;
+    /**
+     * Set when an oversized, not-yet-terminated line/header-less run was just
+     * discarded with no newline in hand. The bytes that eventually complete
+     * that same logical line are not a delimiter the reader can trust as the
+     * start of a fresh frame, so every byte up to and including the next 0x0a —
+     * however many chunks it takes to arrive — is swallowed unread before
+     * normal parsing resumes. See `rejectOversizedIncompleteInput`.
+     */
+    discardingOversizedLine = false;
     /**
      * @param options.maxFrameBytes Largest accepted frame; defaults to
      *   {@link loadMaxFrameBytes}.
@@ -206,6 +217,7 @@ export class JsonRpcFrameReader {
         this.awaitedFrameEnd = -1;
         this.awaitedBodyStart = -1;
         this.fatal = false;
+        this.discardingOversizedLine = false;
     }
     clear() {
         this.clearIdleTimer();
@@ -216,6 +228,7 @@ export class JsonRpcFrameReader {
         this.awaitedFrameEnd = -1;
         this.awaitedBodyStart = -1;
         this.fatal = false;
+        this.discardingOversizedLine = false;
     }
     processChunk(chunk, handlers) {
         if (chunk.length === 0 || this.fatal) {
@@ -242,6 +255,24 @@ export class JsonRpcFrameReader {
         this.pendingBytes = 0;
         while (true) {
             try {
+                if (this.discardingOversizedLine) {
+                    // Swallow bytes up to and including the next newline WITHOUT
+                    // interpreting them as a frame — they are the tail of the line just
+                    // rejected as oversized, not a fresh start, even if they happen to
+                    // look like a well-formed message on their own. Only once that
+                    // terminator is found does this resynchronize on the byte position
+                    // the peer itself delimited.
+                    const newlineIndex = this.buffer.indexOf(0x0a);
+                    if (newlineIndex === -1) {
+                        // The discarded bytes carry no information, so there is nothing
+                        // to hold onto while waiting for the terminator.
+                        this.buffer = Buffer.alloc(0);
+                        return;
+                    }
+                    this.buffer = this.buffer.subarray(newlineIndex + 1);
+                    this.discardingOversizedLine = false;
+                    continue;
+                }
                 this.rejectOversizedIncompleteInput();
                 if (this.mode === "unknown") {
                     const detected = this.detectMode();
@@ -297,6 +328,7 @@ export class JsonRpcFrameReader {
                     this.buffer = Buffer.alloc(0);
                     this.pendingChunks = [];
                     this.pendingBytes = 0;
+                    this.discardingOversizedLine = false;
                     handlers.onError(error);
                     return;
                 }
@@ -361,6 +393,28 @@ export class JsonRpcFrameReader {
         handle = this.scheduleTimer(expire, this.incompleteFrameIdleMs);
         this.idleTimer = handle;
     }
+    /**
+     * Whether the buffer, despite `mode` still sticking at "content-length"
+     * from an earlier frame, actually opens a line-mode frame — the same probe
+     * `readContentLengthMessage` uses to detect the mid-stream switch back to
+     * line framing (a JSON object/array opener can never begin a Content-Length
+     * header block). Used to keep the header-size ceiling scoped to buffers
+     * still being accumulated as a header block, so it never judges a line
+     * frame's bytes as an oversized header just because the switch hasn't been
+     * recognized yet.
+     */
+    looksLikeLineFrame() {
+        let probeIndex = 0;
+        while (probeIndex < this.buffer.length &&
+            (this.buffer[probeIndex] === 0x20 ||
+                this.buffer[probeIndex] === 0x09 ||
+                this.buffer[probeIndex] === 0x0d ||
+                this.buffer[probeIndex] === 0x0a)) {
+            probeIndex += 1;
+        }
+        return (probeIndex < this.buffer.length &&
+            (this.buffer[probeIndex] === 0x7b /* '{' */ || this.buffer[probeIndex] === 0x5b /* '[' */));
+    }
     canCompleteFrame(chunk) {
         const bufferedBytes = this.buffer.length + this.pendingBytes;
         if (this.mode === "content-length" && this.awaitedFrameEnd >= 0) {
@@ -373,8 +427,17 @@ export class JsonRpcFrameReader {
         return chunk.includes(0x0a) || bufferedBytes > this.maxFrameBytes;
     }
     rejectOversizedIncompleteInput() {
-        const headerBoundary = this.mode === "content-length" ? findHeaderBoundary(this.buffer) : undefined;
-        if (this.mode === "content-length" &&
+        // Sticky "content-length" mode only means a header block is being
+        // accumulated when the buffer doesn't already look like a line frame; a
+        // JSON object/array opener here is the same mid-stream switch
+        // `readContentLengthMessage` recognizes, just not yet reached. The header
+        // ceiling below must be scoped to actual header accumulation, or a large
+        // line-mode frame arriving right after a Content-Length frame gets judged
+        // as an oversized header before the switch is detected.
+        const isLineFrameAfterContentLength = this.mode === "content-length" && this.looksLikeLineFrame();
+        const inHeaderAccumulation = this.mode === "content-length" && !isLineFrameAfterContentLength;
+        const headerBoundary = inHeaderAccumulation ? findHeaderBoundary(this.buffer) : undefined;
+        if (inHeaderAccumulation &&
             !headerBoundary &&
             this.buffer.length > MAX_CONTENT_LENGTH_HEADER_BYTES) {
             // No header terminator anywhere in an over-limit header block: there is
@@ -387,15 +450,25 @@ export class JsonRpcFrameReader {
         if (this.buffer.length <= this.maxFrameBytes) {
             return;
         }
-        if (this.mode === "content-length" && headerBoundary) {
+        if (inHeaderAccumulation && headerBoundary) {
             return;
         }
-        if (this.mode !== "content-length" && this.buffer.includes(0x0a)) {
+        if (!inHeaderAccumulation && this.buffer.includes(0x0a)) {
             return;
         }
         const observedBytes = this.buffer.length;
-        const description = this.mode === "line" ? "Line-delimited JSON-RPC frame" : "Headerless JSON-RPC input";
+        const description = this.mode === "line" || isLineFrameAfterContentLength
+            ? "Line-delimited JSON-RPC frame"
+            : "Headerless JSON-RPC input";
         this.buffer = Buffer.alloc(0);
+        if (!inHeaderAccumulation) {
+            // The oversized run has no newline anywhere in it yet (the check above
+            // would otherwise have returned): remember to swallow bytes through the
+            // eventual terminator — wherever it arrives — before resuming normal
+            // parsing, so the discarded line's own tail is never re-read as a fresh
+            // frame (see `discardingOversizedLine` in `drainChunk`).
+            this.discardingOversizedLine = true;
+        }
         throw new Error(`${description} is ${observedBytes} bytes, exceeding the configured frame limit of ` +
             `${this.maxFrameBytes} bytes.`);
     }

package/dist/mapping/loaders/tiny-maven.d.ts

@@ -1,2 +1,11 @@
+import type { DirectionIndex, PairKey } from "../internal-types.js";
 import type { MappingLoaderDeps, MappingLoaderResult } from "./types.js";
+/**
+ * `maxEntryBytes` reuses the same ceiling as nested-jar extraction
+ * ({@link loadMaxNestedJarEntryBytes}): the downloaded jar is itself
+ * download-size-capped, but a single `.tiny`/`.tinyv2` entry inside it is
+ * decompressed in full before parsing, so an entry with a small compressed
+ * size and a huge inflated size (zip-bomb style) must still be bounded here.
+ */
+export declare function parseTinyFromJar(jarPath: string, maxEntryBytes?: number): Promise<Map<PairKey, DirectionIndex>>;
 export declare function loadTinyPairsFromMaven(deps: MappingLoaderDeps, version: string): Promise<MappingLoaderResult>;

package/dist/mapping/loaders/tiny-maven.js

@@ -1,4 +1,5 @@
 import { defaultDownloadPath, downloadToCache } from "../../repo-downloader.js";
+import { loadMaxNestedJarEntryBytes } from "../../source/nested-jars.js";
 import { collectMatchedJarEntriesAsUtf8 } from "../../source-jar-reader.js";
 import { mergeDirectionIndexes } from "../parsers/symbol-records.js";
 import { parseTinyMappingsInto } from "../parsers/tiny.js";
@@ -27,8 +28,15 @@ async function fetchYarnCoordinates(fetchFn, repoBase, version) {
         return [version];
     }
 }
-async function parseTinyFromJar(jarPath) {
-    const tinyEntries = (await collectMatchedJarEntriesAsUtf8(jarPath, (entry) => entry.toLowerCase().endsWith(".tiny") || entry.toLowerCase().endsWith(".tinyv2"), { continueOnError: true })).sort((left, right) => left.filePath.localeCompare(right.filePath));
+/**
+ * `maxEntryBytes` reuses the same ceiling as nested-jar extraction
+ * ({@link loadMaxNestedJarEntryBytes}): the downloaded jar is itself
+ * download-size-capped, but a single `.tiny`/`.tinyv2` entry inside it is
+ * decompressed in full before parsing, so an entry with a small compressed
+ * size and a huge inflated size (zip-bomb style) must still be bounded here.
+ */
+export async function parseTinyFromJar(jarPath, maxEntryBytes = loadMaxNestedJarEntryBytes()) {
+    const tinyEntries = (await collectMatchedJarEntriesAsUtf8(jarPath, (entry) => entry.toLowerCase().endsWith(".tiny") || entry.toLowerCase().endsWith(".tinyv2"), { continueOnError: true, maxBytes: maxEntryBytes })).sort((left, right) => left.filePath.localeCompare(right.filePath));
     // Parsed straight into the shared accumulator: a parse-then-merge loop would
     // hold each entry's full index alongside the accumulated one. `ensurePairIndex`
     // + `addLookupEntries` union into what is already there, matching what

package/dist/repo-downloader.js

@@ -771,13 +771,24 @@ async function cachedBytesResult(url, destinationPath, sidecar, cacheStatus) {
  * a zip reader opens it - so it must satisfy neither an immutable hit nor a
  * stale-if-error fallback. Treating it as absent lets the next transfer replace
  * it instead of pinning it forever.
+ *
+ * That equivalence stops at "missing", the same line {@link describeFileIfPresent}
+ * draws: only {@link isMissingFileError} answers a cache miss. A present-but-
+ * unreadable entry (EACCES from a locked-down cache directory, EISDIR, EIO)
+ * propagates instead of collapsing to 0, because this is the first stat this
+ * module makes on the path - collapsing it here would let `resolveCachedDownload`
+ * read "no cached bytes" and fall through to a live transfer without ever
+ * reaching the read path that already reports this failure correctly.
  */
 function cachedByteCount(filePath) {
     try {
         return statSync(filePath).size;
     }
-    catch {
-        return 0;
+    catch (error) {
+        if (isMissingFileError(error)) {
+            return 0;
+        }
+        throw error;
     }
 }
 /**

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

@@ -1,3 +1,4 @@
+import { type JavaSourceScan } from "../source-jar-reader.js";
 import type { SourceService } from "../source-service.js";
 import type { ArtifactContentsSummary, ProbeMinecraftArtifactInput, ProbeMinecraftArtifactOutput, ResolveArtifactInput, ResolveArtifactOutput } from "../source-service.js";
 import type { AccessTransformerNamespace, ArtifactProvenance, ArtifactScope, ArtifactTargetKind, ResolvedSourceArtifact, RuntimeLoader, RuntimeValidationProvenance, SourceMapping } from "../types.js";
@@ -143,6 +144,19 @@ export declare function hasLoaderRuntimeVersionToken(path: string, mcVersion: st
  * of the path is the version the jar was built for.
  */
 export declare function inferRuntimeJarMinecraftVersion(path: string): string | undefined;
+/**
+ * The Minecraft version a `kind: "jar"` target PROVES it is the unobfuscated
+ * runtime of, or undefined. The file path is never evidence: Loom and other
+ * tools lay jars out in ways that path heuristics have misread before.
+ *
+ * All three must hold: the walk met no `.java` entry, the jar ships
+ * `net/minecraft/SharedConstants.class`, and its root `version.json` parses with a
+ * string `id` that `isUnobfuscatedVersion` accepts. The id is put to that test
+ * only once the other two hold, so it is the id a Minecraft `version.json`
+ * declares, never a library's own release number. A Loom-mapped 1.x jar carries
+ * both signals too; its `1.x` id is what keeps it out. The path is never read.
+ */
+export declare function provenUnobfuscatedRuntimeJarVersion(scan: JavaSourceScan | undefined): string | undefined;
 /**
  * Loader a runtime jar belongs to, read from the tool-written part of its path.
  *