@adhisang/minecraft-modding-mcp 7.0.0-rc.2 → 7.0.0

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

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

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

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

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

@@ -16,23 +16,72 @@ const clearIdleTimerHandle = (handle) => {
     clearNodeTimeout(handle);
 };
 /**
- * The FIRST header terminator in the buffer, whichever style it is.
+ * The end of the header block: the FIRST EMPTY LINE in the buffer.
  *
- * Preferring a CRLFCRLF found anywhere over an earlier LFLF mis-framed every
- * LF-framed peer whose JSON body happened to contain a raw `\r\n\r\n` — legal
- * inter-token whitespace — because the header block was then cut at a boundary
- * inside the body, losing that frame and the next.
+ * One rule generates every terminator style instead of a list of literals to
+ * match. A header line ends at an LF, and a CR immediately before that LF
+ * belongs to the terminator rather than to the line; the block ends at the
+ * first line that holds nothing but its own terminator. `index` is the first
+ * byte of that terminating sequence — so `buffer.slice(0, index)` is exactly
+ * the header text — and `delimiterBytes` spans through the empty line's LF, so
+ * the body opens at `index + delimiterBytes`. The four shapes a peer can
+ * produce are consequences, not cases:
+ *
+ *     "\r\n\r\n" → 4 bytes      "\r\n\n" → 3 bytes
+ *     "\n\r\n"   → 3 bytes      "\n\n"   → 2 bytes
+ *
+ * Scanning forward from byte 0 is also what keeps a real terminator ahead of
+ * any byte sequence inside a body: preferring a CRLFCRLF found ANYWHERE over
+ * an earlier LFLF mis-framed every LF-framed peer whose JSON body happened to
+ * contain a raw `\r\n\r\n` — legal inter-token whitespace — because the header
+ * block was then cut at a boundary inside the body, losing that frame and the
+ * next. A single forward scan cannot reach the body before the block ends, so
+ * no body byte can outrank the terminator and no two readings compete.
+ *
+ * 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, 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.
+ *
+ * What that shift COSTS is a separate question, and the answer is not always
+ * "the frame". The usual outcome is a window running off the end of the JSON,
+ * `readContentLengthMessage`'s body-parse failure and a framing-fatal — see
+ * {@link JsonRpcFramingFatalError}. But the window is only shifted, not
+ * mis-sized, so trailing whitespace INSIDE the declared length can absorb the
+ * shift exactly: a length that counts two trailing spaces, against two
+ * uncounted leading bytes, lands the window on `"\r\n" + <json>`, which
+ * `JSON.parse` accepts. Such a frame is delivered normally. The reader does
+ * not detect the extra blank line; it only ever sees where the bytes fall.
  */
 function findHeaderBoundary(buffer) {
-    const crlfBoundary = buffer.indexOf("\r\n\r\n");
-    const lfBoundary = buffer.indexOf("\n\n");
-    if (crlfBoundary !== -1 && (lfBoundary === -1 || crlfBoundary < lfBoundary)) {
-        return { index: crlfBoundary, delimiterBytes: 4 };
-    }
-    if (lfBoundary !== -1) {
-        return { index: lfBoundary, delimiterBytes: 2 };
+    let searchFrom = 0;
+    while (true) {
+        const lineEnd = buffer.indexOf(0x0a, searchFrom);
+        if (lineEnd === -1) {
+            return undefined;
+        }
+        // The next line starts immediately after that LF. It is the empty line
+        // when the only bytes it holds are its own terminator: an optional CR and
+        // then an LF. An out-of-range read is `undefined`, which matches neither
+        // byte, so a truncated tail simply keeps the scan waiting for more input.
+        let cursor = lineEnd + 1;
+        if (buffer[cursor] === 0x0d) {
+            cursor += 1;
+        }
+        if (buffer[cursor] === 0x0a) {
+            // A CR in front of the FIRST LF terminates the preceding header line, so
+            // it is part of the delimiter, not of the headers. Guarding on
+            // `lineEnd > 0` keeps the lookbehind inside the buffer when the block is
+            // terminated at byte 0.
+            const index = lineEnd > 0 && buffer[lineEnd - 1] === 0x0d ? lineEnd - 1 : lineEnd;
+            return { index, delimiterBytes: cursor + 1 - index };
+        }
+        searchFrom = lineEnd + 1;
     }
-    return undefined;
 }
 function parseJsonRpcMessage(json) {
     return parseJSONRPCMessage(JSON.parse(json));
@@ -124,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}.
@@ -159,6 +217,7 @@ export class JsonRpcFrameReader {
         this.awaitedFrameEnd = -1;
         this.awaitedBodyStart = -1;
         this.fatal = false;
+        this.discardingOversizedLine = false;
     }
     clear() {
         this.clearIdleTimer();
@@ -169,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) {
@@ -195,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();
@@ -250,6 +328,7 @@ export class JsonRpcFrameReader {
                     this.buffer = Buffer.alloc(0);
                     this.pendingChunks = [];
                     this.pendingBytes = 0;
+                    this.discardingOversizedLine = false;
                     handlers.onError(error);
                     return;
                 }
@@ -314,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) {
@@ -326,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
@@ -340,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.`);
     }
@@ -435,11 +555,23 @@ export class JsonRpcFrameReader {
                 continue;
             }
             if (/^\s*content-length\s*:/i.test(line)) {
-                // Always re-inject with CRLF: choosing the separator from the next
-                // buffered byte raced byte-granular chunking (the peer's \r may not
-                // have arrived yet, yielding a "\n\r\n" boundary findHeaderBoundary
-                // cannot see). With CRLF both peer styles stay recognizable:
-                // "...\r\n" + "\r\n…" → "\r\n\r\n", "...\r\n" + "\n…" → "\n\n".
+                // `line` has already had its trailing \r stripped, so the terminator
+                // has to be written back. Always re-inject CRLF: choosing the
+                // separator from the next buffered byte raced byte-granular chunking
+                // (the peer's \r may not have arrived yet, so the boundary style would
+                // depend on read timing rather than on the peer), and this keeps the
+                // output independent of arrival.
+                //
+                // It does not cost the FRAMING: findHeaderBoundary sees an empty line
+                // next either way — "...\r\n" + "\r\n…" and "...\r\n" + "\n…" are both
+                // first-empty-line boundaries — so no boundary moves. It does cost one
+                // BYTE when the peer wrote a bare LF, and that byte is measured
+                // against MAX_CONTENT_LENGTH_HEADER_BYTES: an LF-framed header block of
+                // exactly 8192 bytes frames on its own, but re-injected here it
+                // measures 8193 and is rejected. Exactly one block size is affected —
+                // 8192, since anything larger was already over the ceiling — and only
+                // when it follows a line-delimited frame, which is why this is left as
+                // it stands rather than traded for the chunking race.
                 this.buffer = Buffer.concat([Buffer.from(`${line}\r\n`, "utf8"), this.buffer]);
                 this.mode = "content-length";
                 return undefined;

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/minecraft-explorer-service.js

@@ -1,7 +1,7 @@
 import { realpathSync } from "node:fs";
 import { createError, ERROR_CODES } from "./errors.js";
 import { loadConfig } from "./config.js";
-import { artifactSignatureFromFile, normalizeJarPath } from "./path-resolver.js";
+import { normalizeJarPath, readJarStatStamp } from "./path-resolver.js";
 import { createJarEntryReader } from "./source-jar-reader.js";
 import { artifactIdNamesMinecraftRuntime } from "./source/artifact-resolver.js";
 import { matchesMemberPattern } from "./source/member-pattern.js";
@@ -988,7 +988,7 @@ export class MinecraftExplorerService {
             // With no derivable version the conservative "obfuscated" stands — which
             // is also the right default for a dependency jar's own bytecode namespace.
             mappingNamespace: minecraftVersion && isUnobfuscatedVersion(minecraftVersion) ? "mojang" : "obfuscated",
-            jarSignature: artifactSignatureFromFile(jarPath).sourceArtifactId,
+            jarSignature: readJarStatStamp(jarPath).sourceArtifactId,
             generatedAt: new Date().toISOString()
         };
     }

package/dist/path-resolver.d.ts

@@ -1,4 +1,4 @@
-import type { ArtifactSignature } from "./types.js";
+import type { JarStatStamp } from "./types.js";
 export interface ResolvedJarInfo {
     originalPath: string;
     resolvedPath: string;
@@ -9,7 +9,18 @@ export declare function buildJarSignature(stats: {
     mtimeMs: number;
     size: number;
 }): string;
-export declare function artifactSignatureFromFile(jarPath: string): ArtifactSignature;
+/**
+ * Read a jar's stat stamp: it stats the file, it does not read a byte of it.
+ *
+ * The name says stat because a stat is all this is. Artifact identity is
+ * derived and composed in `src/artifact-identity.ts`; nothing this returns is
+ * an artifactId, and nothing keys an artifact by it.
+ *
+ * Its one production caller is the `jarSignature` field in
+ * `src/minecraft-explorer-service.ts`, which publishes this stat-based value to
+ * callers of `get-project-context`.
+ */
+export declare function readJarStatStamp(jarPath: string): JarStatStamp;
 export declare function isSecureJarEntryPath(entryPath: string): boolean;
 /**
  * Validate and normalize a user-supplied jar path input.

package/dist/path-resolver.js

@@ -72,7 +72,18 @@ export function resolveJarPathWithSymlinkCheck(jarPath) {
 export function buildJarSignature(stats) {
     return `${Math.trunc(stats.mtimeMs)}:${stats.size}`;
 }
-export function artifactSignatureFromFile(jarPath) {
+/**
+ * Read a jar's stat stamp: it stats the file, it does not read a byte of it.
+ *
+ * The name says stat because a stat is all this is. Artifact identity is
+ * derived and composed in `src/artifact-identity.ts`; nothing this returns is
+ * an artifactId, and nothing keys an artifact by it.
+ *
+ * Its one production caller is the `jarSignature` field in
+ * `src/minecraft-explorer-service.ts`, which publishes this stat-based value to
+ * callers of `get-project-context`.
+ */
+export function readJarStatStamp(jarPath) {
     const resolvedPath = resolveJarPathWithSymlinkCheck(jarPath).resolvedPath;
     const stats = statSync(resolvedPath);
     return {

package/dist/repo-downloader.d.ts

@@ -11,13 +11,16 @@
  * That claim is scoped to this entry point, not to the `downloads/` directory.
  * Callers that reach for raw {@link downloadToCache} - the version service's
  * Mojang jars, the mapping service's mapping archives - park files under the
- * same root, write no sidecar, and keep their own identity on purpose: a Mojang
- * artifact already carries an upstream SHA-1 contract, and a version jar keeps
- * an `mtimeMs:size` signature. They are a different cache layer, not a
- * migration this module is waiting on. Artifacts on local disk outside the
- * cache entirely (`~/.m2`, the Gradle module cache) are identified by their
- * bytes as well - see `contentSignature` in `source-resolver.ts`, which reuses
- * {@link digestFile} to get there.
+ * same root and write no sidecar: a Mojang artifact already carries an upstream
+ * SHA-1 contract. They are a different cache layer, not a migration this module
+ * is waiting on.
+ *
+ * Every artifactId `src/artifact-identity.ts` composes, in both of its id
+ * spaces, is built on a sha256 of the bytes of the file it names - see
+ * `contentSignature` there, which reuses {@link digestFile} to get it. That
+ * covers artifacts on local disk outside the cache entirely (`~/.m2`, the
+ * Gradle module cache) and a jar or a Minecraft version the caller names
+ * directly.
  */
 export interface DownloadResult {
     ok: boolean;
@@ -109,6 +112,15 @@ export interface CachedDownloadFailure {
  * for a fresh download.
  */
 export type CachedDownloadResult = CachedDownloadSuccess | CachedDownloadFailure;
+/**
+ * Drop every remembered rejection.
+ *
+ * The records are process-local and expire on their own, so this exists for a
+ * caller that wants the next resolve to ask the repositories again without
+ * waiting out {@link REMEMBERED_REJECTION_TTL_MS} - a test isolating itself from
+ * the record another test left behind, above all.
+ */
+export declare function clearRememberedRejections(): void;
 /** The persisted identity and freshness record for one cached download. */
 export interface DownloadSidecar {
     version: number;

package/dist/repo-downloader.js

@@ -40,6 +40,96 @@ const DEFINITIVE_REJECTION_STATUS_CODES = new Set([403, 404, 410]);
 function isDefinitiveRejection(statusCode) {
     return statusCode !== undefined && DEFINITIVE_REJECTION_STATUS_CODES.has(statusCode);
 }
+/**
+ * How long a definitive rejection is remembered, and how many such records are
+ * kept at once.
+ *
+ * Nothing about a FAILED download is recorded anywhere else: only bytes land in
+ * the download cache, so a coordinate whose sources jar does not exist re-issues
+ * the same request to every configured repository on every resolve. That is what
+ * makes a repeated `target`-addressed resolve expensive - the artifact index it
+ * built is reused, but the repository sweep that preceded it is paid again - and
+ * a caller whose first call timed out pays the identical sweep on its retry.
+ *
+ * Only {@link DEFINITIVE_REJECTION_STATUS_CODES} are eligible, because those are
+ * the statuses this module already treats as an answer about the artifact rather
+ * than about the repository's health; the doc comment there is the reasoning.
+ * A 5xx, a 429, a 401, a timeout and a thrown network error are all ineligible,
+ * so a passing fault costs one extra request on the next call rather than
+ * locking the artifact out of reach.
+ *
+ * The window bounds even the eligible ones. Records live in memory only, so the
+ * whole set dies with the process, and an artifact published after its rejection
+ * was recorded is reachable again once the record expires.
+ */
+const REMEMBERED_REJECTION_TTL_MS = 5 * 60_000;
+const REMEMBERED_REJECTION_MAX_ENTRIES = 1024;
+/**
+ * Definitive rejections, keyed by the cache slot AND the url that was refused.
+ *
+ * The slot is in the key because it names the cache directory: two configs
+ * pointed at different cache directories are different caches and must not
+ * inherit each other's verdicts. The url is in the key as well because
+ * `destinationPath` is the caller's to choose, so nothing here may assume the
+ * slot was derived from the url it is being asked about.
+ */
+const rememberedRejections = new Map();
+function rememberedRejectionKey(url, destinationPath) {
+    return `${destinationPath}\u0000${url}`;
+}
+/** The unexpired rejection recorded for this url in this slot, if there is one. */
+function readRememberedRejection(url, destinationPath, now) {
+    const key = rememberedRejectionKey(url, destinationPath);
+    const remembered = rememberedRejections.get(key);
+    if (remembered === undefined) {
+        return undefined;
+    }
+    if (remembered.expiresAt <= now) {
+        rememberedRejections.delete(key);
+        return undefined;
+    }
+    // A copy, so a caller that mutates what it was handed cannot edit the record
+    // every later call is answered from.
+    return { ...remembered.result };
+}
+function rememberRejection(url, destinationPath, result, now) {
+    const key = rememberedRejectionKey(url, destinationPath);
+    // Delete before set, so re-recording a key moves it to the back of the Map's
+    // insertion order - which is the order the eviction below reads as recency.
+    rememberedRejections.delete(key);
+    rememberedRejections.set(key, {
+        expiresAt: now + REMEMBERED_REJECTION_TTL_MS,
+        result: { ...result }
+    });
+    if (rememberedRejections.size <= REMEMBERED_REJECTION_MAX_ENTRIES) {
+        return;
+    }
+    // Over the cap. Expired records first - they answer nothing anyway - and then
+    // oldest-recorded first until the set fits. Deleting during iteration is
+    // defined for a Map: the iterator skips what has already been removed.
+    for (const [candidate, entry] of rememberedRejections) {
+        if (entry.expiresAt <= now) {
+            rememberedRejections.delete(candidate);
+        }
+    }
+    for (const candidate of rememberedRejections.keys()) {
+        if (rememberedRejections.size <= REMEMBERED_REJECTION_MAX_ENTRIES) {
+            break;
+        }
+        rememberedRejections.delete(candidate);
+    }
+}
+/**
+ * Drop every remembered rejection.
+ *
+ * The records are process-local and expire on their own, so this exists for a
+ * caller that wants the next resolve to ask the repositories again without
+ * waiting out {@link REMEMBERED_REJECTION_TTL_MS} - a test isolating itself from
+ * the record another test left behind, above all.
+ */
+export function clearRememberedRejections() {
+    rememberedRejections.clear();
+}
 /** Location of the sidecar describing `destinationPath`. Destination-adjacent. */
 export function downloadSidecarPath(destinationPath) {
     return `${destinationPath}${DOWNLOAD_SIDECAR_SUFFIX}`;
@@ -681,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;
     }
 }
 /**
@@ -737,6 +838,17 @@ export async function resolveCachedDownload(url, destinationPath, options) {
         // cache miss, so fall through to the transfer below - failing here would
         // hand the caller's repository loop an ENOENT as its reason to fail over.
     }
+    if (freshness === "immutable") {
+        // A repository's definitive answer about this url, still inside its window.
+        // Below the cached-bytes hit above on purpose: bytes we hold outrank a
+        // remembered refusal, and the 404 leg further down deliberately keeps the
+        // bytes it found. Only immutable urls are ever recorded, so this can never
+        // answer for a -SNAPSHOT.
+        const remembered = readRememberedRejection(url, destinationPath, Date.now());
+        if (remembered !== undefined) {
+            return remembered;
+        }
+    }
     const conditionalHeaders = freshness === "revalidate" ? conditionalHeadersFor(sidecar) : undefined;
     /**
      * Run the transfer, carrying the cached copy's validators only when asked.
@@ -920,13 +1032,21 @@ export async function resolveCachedDownload(url, destinationPath, options) {
             // this module's call - and the record goes back with them, so a later
             // revalidation that finds the artifact restored still has its validators.
             restoreRetiredSidecar();
-            return {
+            const rejection = {
                 ok: false,
                 statusCode: downloaded.statusCode,
                 etag: downloaded.etag,
                 lastModified: downloaded.lastModified,
                 contentLength: downloaded.contentLength
             };
+            // Remember it, so the next resolve of this url inside the window answers
+            // from here instead of re-issuing the request. Immutable urls only: a
+            // -SNAPSHOT is republished under the same name, so its 404 can be a
+            // publish in progress rather than an answer that will hold.
+            if (freshness === "immutable") {
+                rememberRejection(url, destinationPath, rejection, Date.now());
+            }
+            return rejection;
         }
         // The same stale-if-error reuse, for a repository that answered rather than
         // failed to: a 5xx, a 429, an authentication hiccup. Nothing here says the